How do I troubleshoot CORS errors from my API Gateway API?
Last updated: 2021-01-27
I get the error "No 'Access-Control-Allow-Origin' header is present on the requested resource" when I try to invoke my Amazon API Gateway API. How do I troubleshoot the error?
Cross-Origin Resource Sharing (CORS) errors occur when a server doesn’t return the HTTP headers required by the CORS standard. To resolve a CORS error from an API Gateway REST API or HTTP API, reconfigure the API to meet the CORS standard.
Note: CORS must be enabled at the resource level and can be handled using API Gateway configurations or backend integrations, such as AWS Lambda.
The following example shows how to troubleshoot the No ‘Access-Control-Allow-Origin’ header present CORS error. However, you can use a similar procedure to troubleshoot all CORS errors. For example: Method not supported under Access-Control-Allow-Methods header errors and No ‘Access-Control-Allow-Headers’ headers present errors.
Note: The No 'Access-Control-Allow-Origin' header present error can occur for any of the following reasons:
- The API isn't configured with an OPTIONS method that returns the required CORS headers.
- Another method type (such as GET, PUT, or POST) isn't configured to return the required CORS headers.
- An API with proxy integration or non-proxy integration isn't configured to return the required CORS headers.
- For a private REST API, the incorrect invoke URL is called, or the traffic isn't being routed to the interface virtual private cloud (VPC) endpoint.
Confirm the cause of the error
There are two ways to confirm the cause of a CORS error from API Gateway:
- Create an HTTP Archive (HAR) file when you invoke your API. Then, confirm the cause of the error in the file by checking the headers in the parameters returned in the API response.
- Use the developer tools in your browser to check the request and response parameters from the failed API request.
Enable CORS on your API resource that’s experiencing the error
For REST APIs, see Enable CORS on a resource using the API Gateway console. For HTTP APIs, see Configuring CORS for an HTTP API.
Important: If you configure CORS for an HTTP API, then API Gateway automatically sends a response to preflight OPTIONS requests, even if there isn't an OPTIONS route configured for your API. For a CORS request, API Gateway adds the configured CORS headers to the response from an integration.
While enabling CORS, make sure that you do the following:
- For Gateway Responses for <api-name> API, choose the DEFAULT 4XX and DEFAULT 5XX check boxes.
Note: When you select these default options, API Gateway responds with the required CORS headers, even when a request doesn't reach the endpoint. For example, if a request includes an incorrect resource path, API Gateway still responds with a 403 "Missing Authentication Token" error.
- For Methods, choose the check box for the OPTIONS method if it isn't already selected. Also, choose the check boxes for all of the other methods that are available to CORS requests. For example: GET, PUT, and POST.
Note: Enabling CORS in the API Gateway console adds an OPTIONS method to the resource if one doesn’t already exist. It also configures the OPTIONS method's 200 response with the required Access-Control-Allow-* headers. If you already enabled CORS using the console, enabling it again overwrites existing values.
Configure your REST API integrations to return the required CORS headers
Configure your backend AWS Lambda function or HTTP server to send the required CORS headers in its response. To return a list of domains in Access-Control-Allow-Origin, you must configure your backend to send the domain names in a list as the value for the header Access-Control-Allow-Origin.
Important: If you use a proxy integration, you can't set up an integration response in API Gateway to modify the response parameters returned by your API's backend. In a proxy integration, API Gateway forwards the backend response directly to the client.
Note: For APIs with a non-proxy integration, enabling CORS on a resource using the API Gateway console automatically adds the required CORS headers to the resource.
Check the private DNS setting of your interface endpoint (for private REST APIs only)
If private DNS is enabled for the interface endpoint, call your private API from within your Amazon Virtual Private Cloud (Amazon VPC) using the private DNS name to avoid CORS errors.
If private DNS isn't enabled, manually route traffic from the invoke URL to the IP addresses of the VPC endpoint.
Note: Use the following invoke URL whether private DNS is enabled or not: https://api-id.execute-api.region.amazonaws.com/stage-name. Make sure that you replace the values for api-id, region, and stage-name with the required values for your API.
For more information, see How to invoke a private API.
Important: If CORS is enabled when private DNS isn't enabled, keep in mind the following limitations:
- You can't use endpoint-specific public DNS names to access your private API from within your Amazon VPC.
- You can't use the Host header option, because requests from a browser don't allow Host header manipulation.
- You can’t use the x-apigw-api-id custom header, because it triggers a preflight OPTIONS request that doesn't include the header. API calls that use the x-apigw-api-id header won’t reach your API.