vercel/next.js · error

To use middleware you must provide a `hostname` and `port` t

Error message

To use middleware you must provide a `hostname` and `port` to the Next.js Server

What it means

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.

Source

Thrown at packages/next/src/server/next-server.ts:1682

    let url: string

    if (this.nextConfig.skipProxyUrlNormalize) {
      url = getRequestMeta(params.request, 'initURL')!
    } else {
      // For middleware to "fetch" we must always provide an absolute URL
      const query = urlQueryToSearchParams(params.parsed.query).toString()
      const locale = getRequestMeta(params.request, 'locale')

      url = `${getRequestMeta(params.request, 'initProtocol')}://${
        this.fetchHostname || 'localhost'
      }:${this.port}${locale ? `/${locale}` : ''}${params.parsed.pathname}${
        query ? `?${query}` : ''
      }`
    }

    if (!url.startsWith('http')) {
      throw new Error(
        'To use middleware you must provide a `hostname` and `port` to the Next.js Server'
      )
    }

    const page: {
      name?: string
      params?: { [key: string]: string | string[] }
    } = {}

    const middleware = await this.getMiddleware()
    if (!middleware) {
      return { finished: false }
    }
    if (!(await this.hasMiddleware(middleware.page))) {
      return { finished: false }
    }

    await this.ensureMiddleware(params.request.url)

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Pass `hostname` and `port` to the NextServer/NextNodeServer options when constructing your custom server.
2. If not using a custom server, run via `next start`/`next dev` which supplies these automatically.
3. Check that skipProxyUrlNormalize and any custom request metadata (initURL/initProtocol) produce an http(s) absolute URL.
4. Ensure your reverse proxy forwards the correct protocol header (X-Forwarded-Proto) so initProtocol resolves to http/https.

Example fix

// before
const app = next({ dev })
// after
const app = next({ dev, hostname: '0.0.0.0', port: 3000 })

const opts = { dev, hostname, port }
if (!opts.hostname || !opts.port) {
  throw new Error('hostname and port are required for middleware support')
}
const app = next(opts)

function hasServerAddress(o: { hostname?: unknown; port?: unknown }): boolean {
  return typeof o.hostname === 'string' && typeof o.port === 'number' && o.port > 0
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Middleware is not supported in minimal mode. Please remove t
• Config options `experimental.proxyClientMaxBodySize` and `ex
• Config options `experimental.proxyPrefetch` and `experimenta
• Config options `experimental.externalProxyRewritesResolve` a
• Config options `skipProxyUrlNormalize` and `skipMiddlewareUr

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/f8c1a02b86a0381e. Report an issue: GitHub.