Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A browser blocks a request to a Next.js API route with a CORS error

ErrorAccess to fetch at 'https://api.example.com/api/items' from origin 'https://app.example.com' has been blocked by CORS policy

Short answer

Next.js adds no CORS headers by itself. The browser blocks the response until your route sends them. Add Access-Control-Allow-Origin through next.config headers, a Route Handler or Proxy, answer the OPTIONS preflight with the allowed methods and headers, and use a named origin, not a wildcard, when cookies are sent.

  • Applies to Next.js 15, Next.js 16, Chrome, Firefox
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Send the preflight yourself and read the response headers. If Access-Control-Allow-Origin is missing, the server never sent it.

    curl -i -X OPTIONS https://api.example.com/api/items -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: POST"
  2. 2Match what you see, then jump to its fix

    1. 1The response has no Access-Control-Allow-Origin header at allNo CORS headers are set on the routeFix
    2. 2GET works but POST with JSON or an Authorization header fails with a preflight errorThe OPTIONS preflight is answered without CORS headersFix
    3. 3The request uses credentials: 'include' and Access-Control-Allow-Origin is *Cookies are sent but the origin is a wildcardFix
    4. 4OPTIONS gets a redirect or 401 from your login logicProxy blocks the preflight before the route runsFix

What does the error look like?

  • Access to fetch at 'https://api.example.com/api/items' from origin 'https://app.example.com' has been blocked by CORS policy
  • Response to preflight request doesn't pass access control check

Cause 1 of 4

No CORS headers are set on the route

1Check

Call the route with the Origin header and look at the response headers.

curl -i https://api.example.com/api/items -H "Origin: https://app.example.com"

2Fix

Set the headers for the API paths in next.config. Replace the origin with your own site.

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/api/:path*',
        headers: [
          { key: 'Access-Control-Allow-Origin', value: 'https://app.example.com' },
          { key: 'Access-Control-Allow-Methods', value: 'GET, POST, PUT, DELETE, OPTIONS' },
          { key: 'Access-Control-Allow-Headers', value: 'Content-Type, Authorization' },
        ],
      },
    ]
  },
}

3Verify

Restart the server and repeat the curl; the headers should appear.

curl -i https://api.example.com/api/items -H "Origin: https://app.example.com" | grep -i access-control

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 4

The OPTIONS preflight is answered without CORS headers

1Check

The Route Handler docs say that if you do not define OPTIONS, Next.js implements it and sets only the Allow header. That reply carries no Access-Control headers.

curl -i -X OPTIONS https://api.example.com/api/items -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: POST"

2Fix

Export your own OPTIONS handler that returns the CORS headers.

// app/api/items/route.ts
const cors = {
  'Access-Control-Allow-Origin': 'https://app.example.com',
  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
}

export async function OPTIONS() {
  return new Response(null, { status: 204, headers: cors })
}

export async function POST(request: Request) {
  return Response.json({ ok: true }, { headers: cors })
}

3Verify

Repeat the OPTIONS curl; it should return 204 with the three headers.

curl -i -X OPTIONS https://api.example.com/api/items -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: POST"

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 4

Cookies are sent but the origin is a wildcard

1Check

MDN states that for a credentialed request the server must not use the * wildcard for Access-Control-Allow-Origin. It must name one origin.

curl -i https://api.example.com/api/items -H "Origin: https://app.example.com" | grep -i access-control

2Fix

Return the exact requesting origin when it is on your allow-list, add Access-Control-Allow-Credentials: true, and add Vary: Origin.

const allowed = ['https://app.example.com']

export async function GET(request: Request) {
  const origin = request.headers.get('origin') ?? ''
  const headers: Record<string, string> = { Vary: 'Origin' }
  if (allowed.includes(origin)) {
    headers['Access-Control-Allow-Origin'] = origin
    headers['Access-Control-Allow-Credentials'] = 'true'
  }
  return Response.json({ ok: true }, { headers })
}

3Verify

Call it from the browser with credentials: 'include'; the cookie request should now succeed.

curl -i https://api.example.com/api/items -H "Origin: https://app.example.com" | grep -i "access-control\|vary"

Confirmed by developer.mozilla.org

Did this fix it?

Cause 4 of 4

Proxy blocks the preflight before the route runs

1Check

Without a matcher, Proxy runs on every request. Preflight requests never carry credentials, so auth logic in Proxy rejects them.

grep -rn "matcher" proxy.ts middleware.ts 2>/dev/null

2Fix

Answer OPTIONS first in Proxy, as the Next.js docs show, or exclude the API paths from the matcher.

// proxy.ts
export function proxy(request: NextRequest) {
  if (request.method === 'OPTIONS') {
    return new NextResponse(null, { status: 204, headers: corsHeaders })
  }
  // auth checks below
}

3Verify

Repeat the OPTIONS curl without any cookie.

curl -i -X OPTIONS https://api.example.com/api/items -H "Origin: https://app.example.com"

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Allow a list of known origins, never * together with cookies.
  • Add a preflight test (curl OPTIONS) to your API checks.
  • Keep CORS in one place: next.config headers, or one shared helper used by every route.

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

Web apps

A POST to a Google Apps Script web app returns 405 or a CORS error

Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Apps Script web apps run doPost for POST and doGet for GET, and the Apps Script guides describe no other entry points.

3 causes, each with a fix

Web apps

A Chrome extension content script cannot read another site's response

Access to fetch at 'https://api.example.com/price' from origin 'https://shop.example.net' has been blocked by CORS policy

Since Chrome 85 a content script's request is treated as a request from the web page it runs in, so the page's CORS rules apply and the extension's host permissions do not help.

3 causes, each with a fix

Next step

Want this handled for good?

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