CORS preflight: Definition, Use Cases, and Examples

CORS preflight is an OPTIONS request that the browser sends before a "complex" cross-origin request (non-standard headers, PUT/DELETE methods). The server must respond 200 with Access-Control-Allow-Methods / Headers. If preflight fails, the main request is not sent. Common cause of "CORS errors" in the browser console.

Open tool →

CORS (Cross-Origin Resource Sharing) preflight requests are an essential part of web security, ensuring that a web application can safely interact with resources from different origins. When a browser detects a request that may not be safe, such as those using HTTP methods other than GET or POST, or those that include custom headers, it performs a preflight request using the OPTIONS method.

The preflight request checks with the server to see if the actual request is safe to send. The server must respond with the appropriate Access-Control-Allow-Methods and Access-Control-Allow-Headers headers to indicate which methods and headers are permitted. If the server does not respond correctly, the browser will block the actual request and log a CORS error in the console.

For example, if a client attempts to send a PUT request to a different domain, the browser will first send an OPTIONS request to that domain to verify if the server allows PUT requests. If the server responds with:

• Access-Control-Allow-Methods: GET, POST, PUT
• Access-Control-Allow-Headers: Content-Type

Then the browser will proceed with the original PUT request. If not, it will terminate the request and display a CORS error.

Debugging CORS preflight errors can be challenging, especially when dealing with complex applications. Here are steps and tips to effectively identify and resolve these issues:

• Check Network Requests: Use browser developer tools (F12) to inspect the network tab. Look for the OPTIONS request and examine the response headers. Ensure that Access-Control-Allow-Origin is present and correctly configured.
• Validate Server Configuration: If using a web server like Nginx or Apache, ensure that CORS headers are enabled in the server configuration. For example, in Nginx:

• Inspect Error Messages: Pay attention to the console messages when a CORS error occurs. They often provide clues about what is misconfigured.
• Test with CURL: Use CURL to simulate requests and check server responses. For example, to test a preflight request:

This command will return the server's response headers, allowing you to verify if they are set correctly. If you receive a response without the expected CORS headers, that’s a clear indication of misconfiguration.

Configuring CORS preflight requests correctly is crucial for maintaining application security and functionality. Here are best practices to follow:

• Limit Allowed Origins: Instead of using a wildcard (*), specify allowed origins explicitly to restrict access. For example:
add_header 'Access-Control-Allow-Origin' 'https://example.com';
• Specify Allowed Methods: Only allow the HTTP methods that your application requires. For example:
add_header 'Access-Control-Allow-Methods' 'GET, POST';
• Control Allowed Headers: Limit the headers that can be sent in requests. For example, if your API only requires Content-Type, configure it as follows:
add_header 'Access-Control-Allow-Headers' 'Content-Type';
• Implement Caching: Use the Access-Control-Max-Age header to cache preflight responses. This reduces the number of preflight requests:
add_header 'Access-Control-Max-Age' '86400';
• Test Thoroughly: Always test CORS configurations in various environments (development, staging, production) to catch any discrepancies in how headers are handled.

By adhering to these best practices, you can ensure that your CORS preflight requests are secure, efficient, and functional, minimizing the risk of errors and enhancing the overall user experience.