Why this matters
A CORS error is the browser enforcing the same-origin policy. Your page can make a request to another origin, but the browser will not let JavaScript read the response unless the other server explicitly permits it. The familiar console message is therefore not a general HTTP failure: the server may have received the request, completed it, and returned data successfully. The browser can still hide that response from the page because the response did not satisfy the server’s CORS policy.
This distinction matters because the visible error rarely identifies the actual defect. A missing Access-Control-Allow-Origin header, an incorrect allowed origin, an unapproved request header, or a failed preflight can produce nearly identical console output. The useful debugging task is to determine which request was made, whether it was preceded by a preflight, what the browser asked for, and what the server returned. Those details appear in the browser’s request and response headers, not in the generic CORS message.
The browser’s origin includes the scheme, host, and port. For example, https://app.example.test and https://api.example.test are different origins even though both use HTTPS. This is why a server that works when opened directly can still fail when called by a page hosted elsewhere. CORS is also not an authentication mechanism: it controls whether browser code may read a cross-origin response, not who is allowed to call an API.
The process
- Reproduce the request while inspecting browser network activity. Open the browser developer tools, select the Network view, and trigger the action that produces the error. Locate the failing request and open its Headers view. The Console message is useful as a signal, but the request details are needed to diagnose it.
- Identify the requesting and requested origins. Note the origin of the page making the call and the full URL of the target resource. Compare the scheme, hostname, and port rather than looking only at the hostname. A difference in any of those three parts creates a cross-origin request.
- Determine whether the browser sent the actual request. Check the request method, status, and timing. If the only visible entry is an OPTIONS request, the browser has not yet sent the actual GET, POST, PUT, PATCH, or DELETE operation. If the actual request appears but the page cannot read its response, inspect the response headers for the CORS policy.
- Read the request headers that define the CORS check. For a preflight, look for Origin, Access-Control-Request-Method, and Access-Control-Request-Headers. These show which origin is asking, which method it wants to use, and any non-safelisted headers it wants to include. For the actual request, Origin is still important even when no preflight occurs.
- Read the response headers that grant or deny access. Look for Access-Control-Allow-Origin on the relevant response. A preflight may also need Access-Control-Allow-Headers and Access-Control-Allow-Methods. If the browser is sending credentials, the response must include Access-Control-Allow-Credentials: true. Also check Access-Control-Expose-Headers when the page needs to read a non-safelisted response header.
- Inspect a fetchable URL with the header analyzer. In the http-headers-analyzer tool, type the target URL into the field labeled Enter URL to analyze. This is useful for seeing the headers returned for a resource that the analyzer’s browser context can actually retrieve. Because the analyzer has no backend and performs its request from the browser, the URL you enter must be accessible to that browser context; a cross-origin resource blocked by CORS may fail before its headers can be analyzed.
- Check the response payload separately when needed. The json-formatter tool accepts a .json file and provides format, minify, and validate modes. If you have already copied or saved the response body as a JSON file, you can upload it to check whether the payload is valid JSON. This helps distinguish malformed response data from a CORS denial, but the formatter does not fetch the API or diagnose its response headers.
- Use the port scanner only to test basic reachability. Enter the server in Hostname or IP Address, then set Start Port and End Port. A scan range can contain at most 1000 ports. If the expected HTTP or HTTPS port is not reachable, the problem is below the CORS layer. An open port does not prove that CORS is configured correctly, so continue examining the HTTP response.
- Assign the fix to the side that controls the policy. A missing or incorrect CORS allowance normally belongs in the API server, gateway, or hosting configuration. The frontend owner usually chooses the request URL and headers, but cannot grant its own page permission to read another server’s response. A frontend team can avoid the issue by using a same-origin endpoint or a correctly configured server-side proxy, but it should not treat a browser-side header as a substitute for a server policy.
Worked example
Suppose a page at https://app.example.test sends a POST request to https://api.example.test/orders. The request body is JSON and includes an Authorization header. The Console reports a CORS failure, and a developer initially assumes that the POST handler is broken because the order never appears in the interface.
Network inspection shows an OPTIONS request first. Its request headers contain Origin: https://app.example.test, Access-Control-Request-Method: POST, and Access-Control-Request-Headers: authorization, content-type. The OPTIONS response has status 204 but no Access-Control-Allow-Origin or Access-Control-Allow-Headers. The browser consequently stops before sending the actual POST. In this case, the server-side CORS configuration must allow the page’s exact origin, the POST method, and both requested headers. If the frontend uses credentialed requests, it must also return Access-Control-Allow-Credentials: true; a wildcard origin is not valid with credentials.
Now suppose the preflight is successful and the POST returns status 200, but the response contains only Access-Control-Allow-Origin: https://other.example.test. The policy names a different origin, so the browser still blocks access. Alternatively, if there is no preflight and the actual GET response lacks Access-Control-Allow-Origin entirely, the fix is still on the server response. The http-headers-analyzer may help confirm the returned policy for a URL it can fetch. The json-formatter can separately validate a saved JSON response, while the port scanner can confirm that the API host and port are reachable.
Common mistakes
- Changing frontend request code without examining headers. Rewriting fetch calls or adding headers may change whether a preflight is needed, but it cannot create CORS permissions on the response. The decisive evidence is in the request and response headers.
- Confusing a successful preflight with a successful application request. OPTIONS can pass while the subsequent POST or GET fails. Inspect both exchanges, including the actual response status and CORS headers.
- Allowing every origin without considering the application’s trust model. A wildcard may satisfy simple public API access, but it is not usable with credentialed browser requests and can expose authenticated endpoints to inappropriate origins.
- Forgetting to approve requested headers. If the preflight lists authorization, content-type, or another header, the response must explicitly permit it. Returning only the origin and method is not enough.
- Assuming an open port means CORS is working. The port scanner tests reachability. A reachable service can still return responses with missing CORS headers, while a closed port prevents the browser from obtaining any policy at all.
- Trying to inspect a cross-origin response with a browser-based analyzer. The http-headers-analyzer has no backend, so its own fetch can be stopped by the same policy you are trying to diagnose. Use the browser’s network view for blocked cross-origin responses and treat analyzer results as available only when the request succeeds.
- Using a JSON formatter to diagnose transport policy. Valid JSON confirms the shape of a payload you already possess. It says nothing about whether the browser was permitted to retrieve that payload or which headers the server returned.
Limitations of this approach
- Browser errors can hide the response body. Once the same-origin policy blocks access, the browser may show only a CORS failure. The server-side access log may still contain the completed request and its status, which is useful evidence that the request itself succeeded.
- The http-headers-analyzer cannot bypass browser restrictions. It is a pure client-side tool, so it is the wrong instrument for a URL that its browser context cannot fetch. It also does not reproduce the exact request headers, credentials, and origin of your failing application unless the site provides a way to make those values match.
- The json-formatter requires an existing JSON file. It cannot retrieve a remote response, reveal HTTP headers, or determine why the browser blocked access. It is only a payload-validation step.
- The port scanner does not speak the full CORS policy. It can show whether a host and port are reachable and whether a service is present, but it cannot establish that the service permits the page’s origin or handles preflight correctly.
- Not every cross-origin arrangement should be fixed by opening CORS. If two internal services exchange data server to server, browser CORS rules are irrelevant. For browser-to-server calls, a same-origin deployment or a server-side proxy may be preferable to allowing a public origin.
- Some failures are ordinary HTTP or TLS problems. A DNS failure, refused connection, timeout, certificate error, 404, 401, or 500 must be resolved before a meaningful CORS comparison can be made.
Frequently asked questions
Does a CORS error mean the server rejected the request?
No. It means the browser did not allow page JavaScript to read the response. The request may never have been sent if the preflight failed, or it may have been sent and processed successfully if the actual response failed the CORS check.
Why did the browser send an OPTIONS request?
The browser sends a preflight when the intended request is not a CORS-simple request. A request using a method such as POST can require one, as can a request carrying headers such as Authorization or a non-safelisted Content-Type.
Why is a GET request sometimes sent without a preflight?
A GET can be CORS-simple when it uses the default headers and does not carry credentials requiring a preflight. A GET with a custom header can still trigger OPTIONS, so the method alone does not determine the exchange.
What should Access-Control-Allow-Origin contain?
It should identify an origin the server permits, such as https://app.example.test. The value must match the browser’s Origin request header exactly, including scheme and port. A wildcard is not valid for credentialed requests.
Who should fix a CORS policy?
The server or gateway that returns the response normally owns the CORS headers. Frontend developers can avoid a cross-origin call or introduce a same-origin proxy, but they cannot instruct their browser to ignore the server’s policy.
Can I use the http-headers-analyzer for every failing endpoint?
No. It performs a browser-side request, so another origin’s CORS policy can block the analyzer before it exposes the headers. The browser’s Network view is the more reliable place to inspect a request made by the affected page.
How do I tell a CORS failure from invalid JSON?
Use the browser headers to determine whether access was blocked. If you already have the response body, upload the JSON file to the json-formatter and use its validate mode. A successful JSON validation confirms the payload syntax, not the CORS configuration.
Does the port scanner tell me whether CORS is enabled?
No. It can test whether a port is reachable, but CORS is an HTTP response policy. A reachable API can still produce a CORS error, and an open port provides no evidence that the required headers are present.