Skip to content

docs: explain connecting to next dev --experimental-https - #165

Open
Hecze wants to merge 1 commit into
vercel:mainfrom
Hecze:docs/experimental-https
Open

Hecze wants to merge 1 commit into
vercel:mainfrom
Hecze:docs/experimental-https

Conversation

@Hecze

@Hecze Hecze commented Nov 6, 2026

Copy link
Copy Markdown

What's wrong

1. The getFetchOptions JSDoc says the opposite of what the code does. In src/_internal/nextjs-runtime-manager.ts:

/**
 * Get fetch options for HTTPS requests
 * Automatically allows insecure TLS for HTTPS (self-signed certificates)
 * Can be disabled via NODE_TLS_REJECT_UNAUTHORIZED=0
 */
function getFetchOptions(protocol: "http" | "https") {
  const allowInsecure =
    protocol === "https" && process.env.NODE_TLS_REJECT_UNAUTHORIZED === "0"

Certificates are verified by default, and NODE_TLS_REJECT_UNAUTHORIZED=0 turns verification off. #88 made insecure TLS the default, and #93 switched to strict verification after the review in #88 (comment), but the comment kept the old meaning.

2. Nothing tells users how to reach a dev server started with next dev --experimental-https. mkcert installs its CA in the OS trust store, which Node.js doesn't read, and Next.js passes the CA only to its own server process through NODE_EXTRA_CA_CERTS. The MCP server is a separate Node process, so the certificate check fails and nextjs_index reports no server. With an explicit port it says No MCP tools found on port 3008 ..., and nextjs_call says Cannot connect to Next.js dev server on port 3008. The README doesn't mention HTTPS, NODE_EXTRA_CA_CERTS or NODE_TLS_REJECT_UNAUTHORIZED. #86 (HTTPS through a custom server) hits the same check since #93.

Reproduction

Next.js 16.4.3, Node 24.22.1, Windows 11. I ran next dev --port 3008 --experimental-https with a localhost certificate signed by a throwaway local CA (passed with --experimental-https-ca), so nothing was installed into the OS trust store. A small stdio MCP client started the built dist/index.js with each env and called nextjs_index and nextjs_call:

MCP server env nextjs_index (auto) nextjs_index {port} nextjs_call get_errors
none not found No MCP tools found on port 3008 ... Cannot connect to Next.js dev server on port 3008 ...
NODE_EXTRA_CA_CERTS=<rootCA.pem> found, https://localhost:3008, 9 tools success success
NODE_TLS_REJECT_UNAUTHORIZED=0 found, https://localhost:3008, 9 tools success success, with Node's insecure-TLS warning

A plain next dev on the same port is found with no env, and on a non-standard port (process discovery) the HTTPS server is found with NODE_EXTRA_CA_CERTS and not without it.

Changes

  • src/_internal/nextjs-runtime-manager.ts: the JSDoc now describes the real behavior. Comment only.
  • README.md: one Troubleshooting entry with an env example for NODE_EXTRA_CA_CERTS, where to find the CA path, a note for your own certificate or a custom HTTPS server, and NODE_TLS_REJECT_UNAUTHORIZED=0 as a last resort, with the warning that it turns off verification for every HTTPS request the server makes.

No runtime change, so no changeset. I can add a regression test that pins verify-by-default if you want one; I left it out because it needs a self-signed key and certificate checked into the repo.

Tests

With the repo's pnpm 9.15.9: pnpm build, pnpm typecheck and pnpm test pass (9 test files).

Related: #86, #88, #93

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant