403 Forbidden when a WebSocket API goes through CloudFront
Unexpected response code: 403 during the WebSocket handshakeShort answer
Through CloudFront, a WebSocket handshake needs the right headers forwarded, and API Gateway needs its own host name rather than your CloudFront domain. Attach an origin request policy that forwards the viewer headers except Host (AllViewerExceptHostHeader), and make sure the Sec-WebSocket headers reach the origin.
Fix it fast
1Find out which cause you have
Connect to the API Gateway URL directly. If that works and the CloudFront URL gives 403, the problem is in the CloudFront cache behavior. You can use wscat if you have it, or any WebSocket client.
npx wscat -c wss://abc123.execute-api.us-east-1.amazonaws.com/prod npx wscat -c wss://d111111abcdef8.cloudfront.net/prod2Match what you see, then jump to its fix
What does the error look like?
Unexpected response code: 403 during the WebSocket handshake403 Forbidden on the upgrade request, while the execute-api URL works directly
Cause 1 of 2
CloudFront forwards its own Host header to API Gateway
1Check
Open the cache behavior and read its origin request policy. If the Host header from the viewer is forwarded (for example with the AllViewer policy), the origin gets your CloudFront domain name where it expects its own.
aws cloudfront get-distribution-config --id E2EXAMPLE --query 'DistributionConfig.DefaultCacheBehavior.OriginRequestPolicyId'2Fix
Use the managed origin request policy AllViewerExceptHostHeader (ID b689b0a8-53d0-40ab-baf2-68738e2966ac). It is meant for API Gateway origins, and CloudFront then sets the Host header to the origin's domain name.
# in the distribution config, on the cache behavior:
"OriginRequestPolicyId": "b689b0a8-53d0-40ab-baf2-68738e2966ac"3Verify
Wait for the distribution to finish deploying, then connect through CloudFront again.
npx wscat -c wss://d111111abcdef8.cloudfront.net/prodConfirmed by docs.aws.amazon.com
Cause 2 of 2
The WebSocket handshake headers are not forwarded
1Check
CloudFront needs either all viewer headers forwarded, or at least Sec-WebSocket-Key and Sec-WebSocket-Version named in the origin request policy. A policy that forwards no headers breaks the handshake.
aws cloudfront list-origin-request-policies --type managed --query 'OriginRequestPolicyList.Items[].OriginRequestPolicy.OriginRequestPolicyConfig.Name'2Fix
If you cannot use AllViewerExceptHostHeader, create a custom origin request policy that forwards the WebSocket headers (Sec-WebSocket-Key, Sec-WebSocket-Version, Sec-WebSocket-Protocol, Sec-WebSocket-Accept and Sec-WebSocket-Extensions) and still leaves Host out.
# origin request policy, header names to forward:
Sec-WebSocket-Key
Sec-WebSocket-Version
Sec-WebSocket-Protocol
Sec-WebSocket-Accept
Sec-WebSocket-Extensions3Verify
Connect through the CloudFront domain after the change deploys.
npx wscat -c wss://d111111abcdef8.cloudfront.net/prodConfirmed by docs.aws.amazon.com
How do I stop it coming back?
- Test the execute-api URL directly first, so you know which layer is returning the 403.
- Keep the WebSocket cache behavior separate from your website behaviors.
- Remember CloudFront supports WebSocket only over HTTP/1.1.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Related fixes
Back end
Airflow SSHOperator stops a long script with SSH command timed out
airflow.exceptions.AirflowException: SSH command timed out
SSHOperator waits only 10 seconds for a command by default.
3 causes, each with a fixBack end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack end
ng serve says it cannot determine the project or target
Cannot determine project for command.
The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.
3 causes, each with a fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
ng serve cannot find the dev-server builder package
Could not find the implementation for builder @angular/build:dev-server
The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.
3 causes, each with a fix