{"record":{"id":"f8c1a02b86a0381e","repo":"vercel/next.js","slug":"to-use-middleware-you-must-provide-a-hostname-an","errorCode":null,"errorMessage":"To use middleware you must provide a `hostname` and `port` to the Next.js Server","messagePattern":"To use middleware you must provide a `hostname` and `port` to the Next\\.js Server","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/next/src/server/next-server.ts","lineNumber":1682,"sourceCode":"\n    let url: string\n\n    if (this.nextConfig.skipProxyUrlNormalize) {\n      url = getRequestMeta(params.request, 'initURL')!\n    } else {\n      // For middleware to \"fetch\" we must always provide an absolute URL\n      const query = urlQueryToSearchParams(params.parsed.query).toString()\n      const locale = getRequestMeta(params.request, 'locale')\n\n      url = `${getRequestMeta(params.request, 'initProtocol')}://${\n        this.fetchHostname || 'localhost'\n      }:${this.port}${locale ? `/${locale}` : ''}${params.parsed.pathname}${\n        query ? `?${query}` : ''\n      }`\n    }\n\n    if (!url.startsWith('http')) {\n      throw new Error(\n        'To use middleware you must provide a `hostname` and `port` to the Next.js Server'\n      )\n    }\n\n    const page: {\n      name?: string\n      params?: { [key: string]: string | string[] }\n    } = {}\n\n    const middleware = await this.getMiddleware()\n    if (!middleware) {\n      return { finished: false }\n    }\n    if (!(await this.hasMiddleware(middleware.page))) {\n      return { finished: false }\n    }\n\n    await this.ensureMiddleware(params.request.url)","sourceCodeStart":1664,"sourceCodeEnd":1700,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next/src/server/next-server.ts#L1664-L1700","documentation":"Thrown in the middleware execution path when the absolute URL constructed for the internal middleware fetch does not start with 'http'. Middleware runs as an edge function invoked via a self-fetch, which requires an absolute URL built from this.fetchHostname and this.port; if those are absent/unset the URL is malformed.","triggerScenarios":"Using a custom server (NextServer with customServer) that does not pass `hostname` and `port` options while the app has a middleware.ts; or skipProxyUrlNormalize is set and getRequestMeta('initURL') returns a relative path; or fetchHostname resolves to a value producing a non-http URL.","commonSituations":"Custom Express/Fastify server wrapping Next where the `hostname`/`port` constructor options were omitted; running behind a proxy that strips the protocol; misconfigured i18n locale handling producing a bad URL.","solutions":["Pass `hostname` and `port` to the NextServer/NextNodeServer options when constructing your custom server.","If not using a custom server, run via `next start`/`next dev` which supplies these automatically.","Check that skipProxyUrlNormalize and any custom request metadata (initURL/initProtocol) produce an http(s) absolute URL.","Ensure your reverse proxy forwards the correct protocol header (X-Forwarded-Proto) so initProtocol resolves to http/https."],"exampleFix":"// before\nconst app = next({ dev })\n// after\nconst app = next({ dev, hostname: '0.0.0.0', port: 3000 })","handlingStrategy":"validation","validationCode":"const opts = { dev, hostname, port }\nif (!opts.hostname || !opts.port) {\n  throw new Error('hostname and port are required for middleware support')\n}\nconst app = next(opts)","typeGuard":"function hasServerAddress(o: { hostname?: unknown; port?: unknown }): boolean {\n  return typeof o.hostname === 'string' && typeof o.port === 'number' && o.port > 0\n}","tryCatchPattern":null,"preventionTips":["When using a custom server, always pass hostname and port to next().","Prefer `next start`/`next dev` which supply these automatically.","Add middleware.ts only when running in a server context that provides hostname/port.","Ensure your reverse proxy forwards full absolute URLs/protocol."],"tags":["middleware","custom-server","hostname","port","edge"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}