Specified basePath has to start with a /, found "${result.ba

Error message

Specified basePath has to start with a /, found "${result.basePath}"

What it means

A non-empty basePath must start with '/' so the router can build absolute internal paths. Normalization throws if basePath is truthy, non-empty, not '/', and does not start with '/'. This catches values like 'docs' or 'app/' that are missing the leading slash.

Source

Thrown at packages/next/src/server/config.ts:626

      `Specified assetPrefix is not a string, found type "${typeof result.assetPrefix}" https://nextjs.org/docs/messages/invalid-assetprefix`
    )
  }

  if (typeof result.basePath !== 'string') {
    throw new Error(
      `Specified basePath is not a string, found type "${typeof result.basePath}"`
    )
  }

  if (result.basePath !== '') {
    if (result.basePath === '/') {
      throw new Error(
        `Specified basePath /. basePath has to be either an empty string or a path prefix"`
      )
    }

    if (!result.basePath.startsWith('/')) {
      throw new Error(
        `Specified basePath has to start with a /, found "${result.basePath}"`
      )
    }

    if (result.basePath !== '/') {
      if (result.basePath.endsWith('/')) {
        throw new Error(
          `Specified basePath should not end with /, found "${result.basePath}"`
        )
      }

      if (result.assetPrefix === '') {
        result.assetPrefix = result.basePath
      }
    }
  }

  if (result?.images) {

View on GitHub (pinned to 0ae8c72462)

Solutions

Prepend a slash: `basePath: '/docs'`
Omit basePath to serve from root

Example fix

// before
module.exports = { basePath: 'docs' }
// after
module.exports = { basePath: '/docs' }

Defensive patterns

Strategy: validation

Validate before calling

if (basePath && basePath !== '' && !basePath.startsWith('/')) {
  basePath = '/' + basePath
}

Type guard

const isValidBasePath = (v: unknown): v is string =>
  typeof v === 'string' && (v === '' || v.startsWith('/'))

Prevention

Always prefix basePath with a leading slash
Validate basePath shape with a regex like /^\/[^/]*[^/]$/ before setting it

When it happens

Trigger: Setting `basePath: 'docs'`, `basePath: 'app'`, or any non-empty string not beginning with '/'. Checked after the '/' and trailing-slash guards in loadConfig.

Common situations: Forgetting the leading slash when copying a sub-path. Reading a path segment from an env var or URL that omits the slash.

Related errors

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