Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A CORS error appears only when the API is reached through an ngrok URL

ErrorYou are about to visit <host>: served for free through ngrok.com

Short answer

Through ngrok the browser can get ngrok's own warning page instead of your API response, and that page carries no CORS headers. Send an ngrok-skip-browser-warning header to skip it, then make sure the Express cors setup allows that header and the origin your page is served from. Check with curl first to see which reply you really get.

  • Applies to ngrok free plan, Express 4 and 5, cors middleware, axios 1.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Request the ngrok URL without a browser. If the body is ngrok's warning page and not your JSON, the first cause below applies. If it is your JSON, go to the other two.

    curl -i https://YOUR-SUBDOMAIN.ngrok-free.app/api/ping
    curl -i -H "ngrok-skip-browser-warning: 1" https://YOUR-SUBDOMAIN.ngrok-free.app/api/ping
  2. 2Match what you see, then jump to its fix

    1. 1The first curl returns an HTML page that says you are about to visit the site; the second one returns your JSON.ngrok's free-tier warning page answers the browser instead of your APIFix
    2. 2The preflight fails and the browser console names a missing token in Access-Control-Allow-Headers.The server's allowedHeaders list does not include the new headerFix
    3. 3The preflight succeeds on localhost but the Access-Control-Allow-Origin header is missing when the front end itself is opened through ngrok.The allowed origin is not the origin the page is loaded fromFix

What does the error look like?

  • You are about to visit <host>: served for free through ngrok.com
  • missing token 'xyz' in CORS header 'Access-Control-Allow-Headers' from CORS preflight channel

Cause 1 of 3

ngrok's free-tier warning page answers the browser instead of your API

1Check

On the free plan ngrok puts an interstitial in front of HTML browser traffic. A client can skip it by sending the ngrok-skip-browser-warning request header with any value, or a custom User-Agent. Paid plans do not show it.

curl -s -H "ngrok-skip-browser-warning: 1" https://YOUR-SUBDOMAIN.ngrok-free.app/api/ping

2Fix

Add the header to the client calls. Because it is not a CORS-safelisted header, the browser will now send a preflight, which the next cause covers.

axios.post(url, body, {
  headers: { 'ngrok-skip-browser-warning': '1' },
});

3Verify

Repeat the request in the browser and look at the Network tab: the response should be your JSON, not HTML.

curl -i -H "ngrok-skip-browser-warning: 1" https://YOUR-SUBDOMAIN.ngrok-free.app/api/ping

Confirmed by ngrok.com

Did this fix it?

Cause 2 of 3

The server's allowedHeaders list does not include the new header

1Check

Any manually set header outside the safelisted ones triggers a preflight, and the server must list it in Access-Control-Allow-Headers. The Express cors middleware reflects the requested headers when allowedHeaders is not set, so this only bites when your code sets an explicit list.

grep -rn "allowedHeaders" --include=*.js --include=*.ts .

2Fix

Add the header to the list, or remove the option to let the middleware reflect what the browser asks for.

app.use(cors({
  origin: 'https://app.example.com',
  allowedHeaders: ['Content-Type', 'Authorization', 'ngrok-skip-browser-warning'],
}));

3Verify

Send the preflight by hand and read the Access-Control-Allow-Headers line in the reply.

curl -i -X OPTIONS https://YOUR-SUBDOMAIN.ngrok-free.app/api/ping \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: ngrok-skip-browser-warning"

Confirmed by github.com

Did this fix it?

Cause 3 of 3

The allowed origin is not the origin the page is loaded from

1Check

The origin option sets Access-Control-Allow-Origin. If your list holds only http://localhost:3000 and the front end is now opened from an ngrok address, the page's origin is a different one and is not on the list.

grep -rn "origin" server.js

2Fix

Put the exact origin of the page, scheme and host, in the list.

app.use(cors({
  origin: ['http://localhost:3000', 'https://YOUR-FRONTEND.ngrok-free.app'],
}));

3Verify

Run the preflight curl above with that Origin and look for Access-Control-Allow-Origin in the reply.

curl -i -X OPTIONS https://YOUR-SUBDOMAIN.ngrok-free.app/api/ping \
  -H "Origin: https://YOUR-FRONTEND.ngrok-free.app" \
  -H "Access-Control-Request-Method: POST"

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Test every ngrok URL with curl before the browser, so you see the real response.
  • Keep the list of allowed origins in one place and update it when the tunnel address changes.
  • Remember that a paid ngrok plan does not show the warning page.

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.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.