Table of Contents
This tutorial was written by Cameron Pavey, a full-stack developer living and working in Melbourne. You can connect with them on X to see more of their work!
Cross-Origin Resource Sharing (CORS) is a mechanism through which browsers determine whether to block frontend JavaScript code from making cross-origin requests. Cross-origin requests occur whenever your application calls an API hosted on a different origin. In practice, they often make up the majority of your API calls. But they also commonly produce errors.
CORS errors are issues with cross-origin requests. They result in error messages and requests that cannot be fulfilled. There are several reasons CORS errors can happen, but most fall into one of four main categories. Below, we’ll explain what causes the most common kinds of CORS errors and how you can fix them.
This article will cover:
Four of the most common CORS errors
How to bypass CORS errors
When not to bypass CORS (and why)
CORS configuration best practices
What is a CORS error, and why does it happen?
CORS is a browser security mechanism that controls whether cross-origin requests are allowed. CORS errors occur when a request is blocked because one or more CORS security rules have been broken or criteria have not been met.
In practice, CORS errors can be especially common if you're developing a web application where the frontend and backend run on different origins.
For instance, imagine that you have a React application running at a website called example.com, and a corresponding REST API at api.example.com. In this case, you will likely encounter an error if you have not configured CORS correctly on your REST API server:
Before the browser initiates the desired API call, it first issues an OPTIONS request to the remote server that includes current origin. The response for this request will provide the browser with the relevant CORS policy headers so the browser can adhere to it accordingly.
Generally, most CORS errors can be resolved by ensuring that you have a proper, valid CORS configuration. Still, there are numerous discrete errors, each with its own cause.
Mozilla MDN maintains a comprehensive list of CORS errors and how to resolve them, and it is an excellent first stop if you're debugging an obscure CORS issue. That said, there are four CORS errors that are the most likely to happen. Knowing these errors makes them easier to diagnose and fix.
1. CORS Header Access-Control-Allow-Origin Missing
This error indicates that the Access-Control-Allow-Origin header is missing in the response from the backend. This header is needed to override a browser’s same-origin policy, which is a key function of the CORS protocol. If you control the backend, resolving this error can be as simple as modifying the response to include the appropriate headers.
This could also occur if the initial OPTIONS request failed for some reason. Depending on your application's architecture, there are different values you can use here.
For instance, using the previous example again, if your backend is running on api.example.com, and the frontend that will be consuming the request is running on example.com, you would use that as the origin for this header, like so:
Access-Control-Allow-Origin: https://example.comThis fix involves an explicit origin that is used for private APIs.
You can also provide a wildcard as the value (using *). However, this is advisable only if your API is intended to be public. Do not use a wildcard if it's a private, internal API.
It’s also important to note that passing credentials (cookies, auth headers, etc.) isn't allowed when using * as the value (see https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSNotSupportingCredentials).
2. CORS Header Access-Control-Allow-Origin Does Not Match XYZ
Similar to the previous error, this one stops your frontend from being able to consume the request. However, rather than a total lack of a CORS header, this error indicates that the header is present but the permitted origin does not match the origin making the request.
In this case, ensure that the following are true:
The response contains the header.
There is only one such header without duplicates.
The header contains only a single origin.
The origin matches the requester's origin.
If these points are all true, this error should be resolved.
3. CORS Request Not HTTP
This error occurs when an asset is loaded through a different scheme (commonly file://), as CORS can only be used with the HTTP or HTTPS URL schemes. This most often happens when viewing a site through the local file system—opening the file directly in your browser—rather than as an asset served via HTTP(S) from a web server.
In practice, this situation is fairly common when performing local testing or development. Since CORS doesn't support this behavior, it is advised to perform local testing with a local server, as this resolves the issue and makes the experience closer to an actual, live environment.
4. Multiple CORS Header Access-Control-Allow-Origin Not Allowed
This error indicates that the server has sent more than one Access-Control-Allow-Origin header in the response. This is invalid as you should include only a single instance of this header. Additionally, the header's value should only be a single origin or `null`. You cannot provide a list of origins here.
For example, consider a case where you have an internal API that needs to be consumed by numerous clients. You can implement checks in either your application code or your web server (like Nginx or Apache) to determine if the requester's origin is one that you approve of and, if so, reflect the appropriate value in the header.
How to bypass CORS errors
Sometimes, during early development or when working with a backend that you cannot easily change, you may wish you could bypass CORS errors for a while to get on with development.
Warning: While understanding how to bypass CORS can be beneficial for development and debugging purposes, it's crucial to use this practice cautiously due to its security risks. It's recommended you only employ CORS bypass techniques temporarily and only when managing servers under your control. Avoid using these methods for regular web browsing activities.
Disable browser security
As the browser enforces CORS, it can be circumvented client-side without any changes to the server. If you use Google Chrome or a related variant, disabling your browser's web security features is the easiest way to do this without additional dependencies. This should be done only for development and testing, and you should not use the browser in this state for normal web activities.
To disable web security in Chrome, you can use the following commands:
OSX:
open -n -a /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --args --user-data-dir="/tmp/chrome_dev_test" --disable-web-securityFor Windows, create a new shortcut and set its target as follows:
[PATH_TO_CHROME]\chrome.exe" --disable-web-security --disable-gpu --user-data-dir=%LOCALAPPDATA%\Google\chromeTempLinux:
google-chrome --disable-web-securityNOTE: This intervention disables same-origin protections entirely and can come with risks of credential leakage. Practice extreme caution if pursuing this CORS bypass.
Use a browser extension
You can also bypass CORS using a browser extension. These extensions edit the response on its way back to your browser and inject the necessary header and value so that your browser accepts it. Such extensions are available for numerous browsers, including via the official Chrome Web Store, Opera Addons, and Firefox Addons.
As with other bypasses, these tools can open up vulnerabilities, so they are only recommended for temporary debugging.
For this same reason, these fixes should not be used in production testing.
Use a proxy
Finally, you can bypass CORS by routing your requests via a proxy. Proxies designed for this purpose handle the request on your behalf before returning a response to your browser with the appropriate headers. The proxy becomes a same-origin intermediary, which can be a reasonable, low-effort way to check particular requests without CORS restrictions.
However, routing your requests through a third-party proxy brings inherent risks, like credential logging and third-party exposure, so it isn't advisable as a long-term solution.
When not to bypass CORS errors
As you've seen, CORS can be easily bypassed. Because CORS is enforced only by browsers, you might wonder why it exists or whether you can bypass it entirely.
CORS is a valuable web technology that plays a role in mitigating attacks like cross-site request forgery (CSRF). You should disable CORS only for testing and development and, even then, only temporarily.
Consider a case where you use an API intended to be consumed only by backend services. This API might explicitly NOT permit any origins in its CORS headers as this would stop browsers from consuming the API. At the same time, backend services would be free to use the API, as they do not typically implement CORS. You could bypass this restriction using a proxy so your frontend app can call this API. While this may technically work, you may expose credentials and data on the frontend that are never intended to be there, leading to potential security concerns.
A preferable alternative to disabling CORS is implementing it correctly on your backend or web server without exposing internal APIs to browsers. With a proper configuration, any reasonable setup should work correctly without bypassing or disabling CORS.
CORS configuration best practices for production
To correctly configure CORS for production, implement these best practices:
Use explicit allowlists rather than the wildcard (“*”) to limit possible exposure
The wildcard cannot be used when credentials are involved. In these cases, you must return a specific origin.
Limit allowed methods (e.g., GET, POST) to further restrict points of entry
Use HTTPS only to avoid possible security vulnerabilities of plaintext HTTP
Test preflight responses to ensure security, authorization, and functionality
Wrapping up
CORS makes cross-origin requests between apps and websites easier for all parties involved. With proper configuration, the most common kinds of CORS errors can be prevented. And, with a thorough understanding of security principles and best practices, all related issues can be mitigated.
Properly configured CORS is one part of a secure, well-function auth setup. If you’re building authentication into a cross-origin application, the infrastructure complexity can leave you asking a lot of questions. Descope helps developers add authentication, user management, and access control without building identity infrastructure from scratch.
Sign up for a Free Forever account with Descope and start building secure, scalable auth flows today. Have questions about building auth into a cross-origin app? Book time with our experts.
