Fix Next.js CORS and Server Actions Behind HTTPS Tunnels

Why localhost and a public HTTPS URL are different origins

A browser origin is the combination of a URL's scheme, hostname, and port. If any one of those components changes, the browser sees a different origin. For example, http://localhost:3000 and https://app.example.test are different origins because both the scheme and hostname differ. Two localhost addresses can also be different origins when their ports differ.

This distinction matters because a Localtonet HTTP tunnel gives a locally reachable web application a public address. The browser connects to that public address, while the Localtonet client running on the selected device maintains an outbound connection to our relay. The local Next.js process remains the tunnel's target, but the browser-facing origin is the public HTTPS origin rather than the local development origin.

A change of origin does not automatically mean CORS is required. If a page loaded from the public tunnel URL calls a relative endpoint such as /api/profile, the browser normally resolves that endpoint against the same public origin. From the browser's perspective, that is a same-origin request. The fact that the request ultimately reaches a local process through a tunnel does not itself turn the request into a cross-origin fetch.

CORS becomes relevant when browser JavaScript loaded from one origin requests a resource on another. Common examples include a page opened on the public HTTPS origin that still calls an absolute http://localhost:3000/api/... URL, a local frontend calling an API through the public URL, or a separate frontend domain calling a tunneled Next.js API. Server Actions introduce a related but separate origin check, so a rejection involving a Server Action must not automatically be treated as a CORS problem.

Identify CORS, preflight, and Server Action failures correctly

Several failures can look similar in the browser because they all occur after switching from localhost to a public address. Before changing configuration, determine which layer rejected the request. Broadly enabling CORS will not fix a Server Action origin mismatch, and adding a Server Action origin will not make a separate API's CORS response valid.

Start with the browser Network panel

Select the failing request and record its Request URL, Request Method, Status Code, Origin request header, and response headers. If an OPTIONS request appears immediately before the intended request, inspect both entries. The preflight can fail even when the endpoint's GET, POST, or other method would otherwise work.

Also inspect the server terminal. If the application never logs the intended request, the browser may have stopped after a failed preflight. If Next.js logs a Server Action origin or host rejection, work on Server Action validation rather than adding unrelated API headers.

Do not use a command-line success as proof that CORS is correct

CORS is primarily enforced by browsers. A command-line HTTP client can demonstrate that an address is reachable and can show response headers, but it does not reproduce the browser's decision automatically. To test a CORS policy outside the browser, send an explicit Origin header and, for a preflight, send an OPTIONS request with the requested method and requested headers.

Configure CORS only where cross-origin browser access is required

A Next.js API does not need a permissive CORS policy merely because it is reachable through a public URL. If the web page and API use the same public origin, prefer relative URLs and same-origin requests. This removes unnecessary cross-origin complexity and keeps the browser's normal same-origin protections intact.

When a separate trusted frontend must call the API, the API response must explicitly permit that frontend origin. The relevant policy should be limited to the required routes, methods, and request headers. CORS is a response policy, so setting request headers in the frontend cannot grant the frontend permission.

The core CORS response headers

For an App Router route handler, one safe pattern is to compare the incoming Origin with an application-owned allowlist, return the matching origin only when it is trusted, and handle OPTIONS explicitly. The following example uses a custom environment variable named APP_ALLOWED_ORIGIN. That name belongs to this example and is not a built-in Next.js or Localtonet setting.

import { NextRequest, NextResponse } from "next/server";

function corsHeaders(request: NextRequest): Headers {
  const headers = new Headers();
  const requestOrigin = request.headers.get("origin");
  const allowedOrigin = process.env.APP_ALLOWED_ORIGIN;

  if (
    requestOrigin &&
    allowedOrigin &&
    requestOrigin === allowedOrigin
  ) {
    headers.set("Access-Control-Allow-Origin", requestOrigin);
    headers.set("Vary", "Origin");
    headers.set("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
    headers.set("Access-Control-Allow-Headers", "Content-Type");
  }

  return headers;
}

export function OPTIONS(request: NextRequest) {
  const headers = corsHeaders(request);

  if (!headers.has("Access-Control-Allow-Origin")) {
    return new NextResponse(null, { status: 403 });
  }

  return new NextResponse(null, {
    status: 204,
    headers,
  });
}

export async function GET(request: NextRequest) {
  const headers = corsHeaders(request);

  if (
    request.headers.get("origin") &&
    !headers.has("Access-Control-Allow-Origin")
  ) {
    return NextResponse.json(
      { error: "Origin not allowed" },
      { status: 403 }
    );
  }

  return NextResponse.json(
    { ok: true },
    { headers }
  );
}

Adapt the route path, methods, headers, and response data to the application. If the route accepts Authorization or another custom header, the preflight response must permit that exact header. Do not copy a broad list of methods or headers merely to silence the browser.

The actual response also needs the applicable CORS header. Returning correct headers only from OPTIONS is insufficient because the browser checks the response to the real request as well. Error responses deserve the same attention. An authentication failure or validation error without the expected CORS header can appear to frontend code as an opaque CORS failure, hiding the useful application error.

Pages Router endpoints follow the same policy

A Pages Router API handler sets headers through its response object and should terminate an OPTIONS request before running normal endpoint logic. The security model remains the same: validate the origin against a fixed allowlist, return only an approved origin, advertise only supported methods and headers, and ensure the actual response carries the required policy.

Handle cookies and credentialed cross-origin requests safely

Credentialed CORS is stricter than public, unauthenticated cross-origin access. Browser credentials can include cookies and HTTP authentication information. For a cross-origin fetch, the frontend must request the appropriate credentials mode, and the server must explicitly permit credentials. The browser's cookie rules still apply independently.

A response that uses Access-Control-Allow-Origin: * cannot be used for a credentialed browser request. The server must return the specific approved origin and include Access-Control-Allow-Credentials: true. The origin value is exact, including its scheme and port.

If a cookie does not arrive, do not assume CORS is the only issue. Cookie domain, path, expiry, Secure, and SameSite behavior can affect whether a browser stores or sends it. A cookie created for localhost is not automatically a cookie for the public tunnel hostname. Likewise, moving from local HTTP to public HTTPS changes the browser context in which cookie rules are evaluated.

Use the browser's cookie and Network inspection tools to answer four separate questions:

• Did the server send a Set-Cookie header?
• Did the browser accept or block that cookie?
• Does the later request include the cookie?
• Does the response contain the exact credentialed CORS headers required by the requesting origin?

Avoid solving development problems by opening authenticated endpoints to every origin. Keep a development allowlist that names only the frontend origins currently needed. Remove obsolete tunnel origins when addresses change, and keep production origins separate from temporary development values.

Fix Next.js Server Action origin validation separately

Server Actions are not ordinary cross-origin API calls with a different label. Next.js applies framework-side request validation to help protect Server Actions from forged cross-site submissions. In the normal case, the request origin should agree with the host through which the application believes it is being accessed. A public HTTPS tunnel or another reverse-proxy layer can expose a mismatch between the browser-visible origin and the host information received by Next.js.

This is why adding Access-Control-Allow-Origin to an API route may have no effect on a rejected Server Action. CORS headers tell a browser whether it can expose a response. Server Action validation can reject the request on the server before a useful action response exists.

Inspect the values involved in the mismatch

Start with the browser request's Origin and the exact public hostname in the address bar. Then inspect the Next.js server error and the host-related information the application receives. Depending on the deployment path, Next.js may evaluate host or forwarded-host information. Do not overwrite forwarded headers in application code simply to force a match. Those headers are security-sensitive and should represent the trusted proxy path accurately.

Next.js has documented an approved-origins configuration for Server Actions, commonly referred to as allowedOrigins. Its exact placement and supported matching syntax are version-specific. Next.js configuration has changed across releases, so this article intentionally does not provide a copy-and-paste configuration block that could be wrong for the installed release.

The safe configuration objective is stable even when syntax changes: approve only the browser-visible development origin that must submit Server Actions, preserve accurate host information through the proxy path, and restart the Next.js process after changing configuration if that release loads the setting at startup.

Treat the active public address as configuration data rather than hardcoding it throughout the source tree. If a generated tunnel address changes, update the approved development value deliberately. A stable selected subdomain or custom domain can reduce address churn where supported, but exact availability and DNS requirements can vary. Check the current Localtonet dashboard and documentation before relying on either option.

Do not confuse a Server Action with an API route

If another origin needs a general-purpose HTTP interface, consider whether an API route or route handler is the clearer boundary. It can expose an intentional request contract, validate authentication, and apply an explicit CORS policy. Server Actions are closely integrated with Next.js rendering and form workflows, and their origin protection should not be disabled merely to turn them into an unrestricted cross-origin API.

Expose the verified local Next.js application with Localtonet

Complete local verification before adding the tunnel. The application should start with its existing project command, render locally, and process the relevant API request or Server Action from its intended local origin. Use the host and port printed by the development server or defined by the project. This guide does not assume a port because projects can override framework defaults.

With Localtonet, the client application on the device establishes an outbound connection to our relay. This means the workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The device running our client must be able to reach the local Next.js listener.

Our HTTP tunnel documentation provides the current product workflow. The public address remains available only while the selected client is connected and the tunnel is running. Stop or delete the tunnel when public access is no longer required.

Verify the tunnel, CORS policy, and Server Actions independently

A layered verification process makes failures easier to locate. Test basic reachability first, then same-origin behavior, then intentional cross-origin behavior, and finally authenticated or Server Action workflows. Changing multiple policies before retesting makes it difficult to know which change fixed or weakened the application.

Use explicit requests to inspect a preflight

The following command shape can inspect the response to a preflight. Replace every placeholder with the exact public endpoint, trusted frontend origin, intended method, and headers used by the application. The values shown are placeholders, not Localtonet addresses or product commands.

curl -i -X OPTIONS "PUBLIC_ENDPOINT_URL" \
  -H "Origin: TRUSTED_FRONTEND_ORIGIN" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type"

Verify that the response permits the supplied trusted origin, the intended method, and every requested non-simple header. Then inspect the actual request separately. A successful preflight does not prove that authentication, validation, or application execution will succeed.

Troubleshooting common Next.js tunnel failures

The page loads, but frontend requests still point to localhost

Search the browser's Network panel for absolute localhost URLs. A browser opened on the public site interprets localhost as the browser user's own machine, not as the tunnel target. For APIs served by the same Next.js application, prefer a relative URL such as /api/items. If a separate origin is intentional, configure that origin explicitly and verify that the requested service is actually reachable from the browser.

The preflight returns 404 or 405

The route may not handle OPTIONS, middleware may not match it, or another layer may reject it before the route runs. Confirm the preflight's exact URL and ensure that the handler serving that path responds to OPTIONS. A method list in a header does not by itself create an OPTIONS handler.

The preflight works, but the actual request is blocked

Check the CORS headers on the actual response. They must be present on successful responses and relevant error responses. Also compare the allowed origin byte for byte with the browser's Origin. A missing scheme, an extra path, or a different port does not match.

The server reflects the origin, but untrusted sites also work

Reflection without validation is the problem. Build the value from a fixed server-side allowlist. If multiple development origins are necessary, compare against all approved values and return only the one that matched the current request. Add Vary: Origin when the response can differ by origin.

Cookies work locally but disappear through HTTPS

Inspect whether the public response sets a cookie for an appropriate domain and whether the browser reports a blocked-cookie reason. Then check the later request. The localhost cookie jar and public hostname cookie jar are different. For a truly cross-origin request, verify the fetch credentials mode and exact credentialed CORS response as separate steps.

The Server Action still reports an origin mismatch

Confirm that the approved value matches the public hostname currently in use and that the application was restarted if necessary. Check that the setting is valid for the installed Next.js release. If the public address changed, an old approved origin will not match. Also investigate whether an application proxy or custom server is replacing host-related headers.

The tunnel exists, but the public URL is unavailable

Creation and execution are separate lifecycle states. Confirm that the correct Localtonet client is connected and that the tunnel was started. Verify that the client device can reach the configured local IP and port. The public endpoint is available only while that selected client remains connected and the tunnel is running.

The public page works intermittently after code or configuration changes

Determine whether the Next.js process restarted, changed its listener, or stopped during compilation. Recheck the local address first. Also confirm that the environment value containing the development origin was loaded by the running process rather than only written to a file. Avoid adding additional origins until the active configuration is known.

Opening every origin appears to fix the issue

That result proves only that origin policy was involved. It does not make the broad policy appropriate. Restore an explicit allowlist and identify the precise browser origin that needs access. For credentialed endpoints and Server Actions, broad wildcard approval weakens protections and may still fail browser credential rules.

Frequently asked questions