vercel/next.js · error · Error

Invalid urlPath provided to revalidate(), must be a path e.g

Error message

Invalid urlPath provided to revalidate(), must be a path e.g. /blog/post-1, received ${urlPath}

What it means

Thrown by the internal revalidate() function (wired to res.revalidate) when urlPath is not a string or does not start with '/'. On-demand revalidation requires an absolute site path (e.g. /blog/post-1) so Next.js can locate and purge the correct cached route; a relative or malformed path cannot be resolved.

Source

Thrown at packages/next/src/server/api-utils/node/api-resolver.ts:257

        : undefined),
      ...(options.path !== undefined
        ? ({ path: options.path } as CookieSerializeOptions)
        : undefined),
    }),
  ])
  return res
}

async function revalidate(
  urlPath: string,
  opts: {
    unstable_onlyGenerated?: boolean
  },
  req: IncomingMessage,
  context: ApiContext
) {
  if (typeof urlPath !== 'string' || !urlPath.startsWith('/')) {
    throw new Error(
      `Invalid urlPath provided to revalidate(), must be a path e.g. /blog/post-1, received ${urlPath}`
    )
  }
  const headers: HeadersInit = {
    [PRERENDER_REVALIDATE_HEADER]: context.previewModeId,
    ...(opts.unstable_onlyGenerated
      ? {
          [PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER]: '1',
        }
      : {}),
  }
  const allowedRevalidateHeaderKeys = [
    ...(context.allowedRevalidateHeaderKeys || []),
  ]

  if (context.trustHostHeader || context.dev) {
    allowedRevalidateHeaderKeys.push('cookie')
  }

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Pass a site-relative path starting with '/', e.g. res.revalidate('/blog/post-1').
2. Strip the origin from full URLs before revalidating: new URL(input).pathname.
3. Validate/coerce the input to a string and prepend '/' if missing.

Example fix

// before
res.revalidate('blog/post-1')
res.revalidate('https://site.com/blog/post-1')
// after
res.revalidate('/blog/post-1')
res.revalidate(new URL(input).pathname)

function normalizeRevalidatePath(urlPath: unknown): string {
  if (typeof urlPath !== 'string') throw new Error('urlPath must be a string')
  if (urlPath.startsWith('http')) {
    try { urlPath = new URL(urlPath).pathname } catch { /* fall through */ }
  }
  if (!urlPath.startsWith('/')) urlPath = '/' + urlPath
  return urlPath
}

function isRevalidatablePath(p: unknown): p is string {
  return typeof p === 'string' && p.startsWith('/')
}

When it happens

Trigger: Calling res.revalidate('blog/post-1') (missing leading slash), res.revalidate('https://example.com/blog') (a full URL), res.revalidate('') , or res.revalidate(undefined). The check `typeof urlPath !== 'string' || !urlPath.startsWith('/')` fails.

Common situations: Passing a full URL instead of a path; building the path from user input without normalizing; forgetting the leading slash after refactoring route helpers.

Related errors

• Invalid response ${res.status}
• Failed to revalidate ${urlPath}: ${err.message}
• Invalid redirect arguments. Please use a single argument URL
• `after()`: Argument must be a promise or a function
• Preview data is limited to 2KB currently, reduce how much da

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