vercel/next.js · error

`experimental.useTypeScriptCli` checks the complete TypeScri

Error message

`experimental.useTypeScriptCli` checks the complete TypeScript project; `--debug-build-paths` does not limit type checking.

What it means

Warning from verifyAndRunTypeScript when experimental.useTypeScriptCli is enabled and the --debug-build-paths flag was also passed. It clarifies that running tsc via the CLI always checks the complete TypeScript project, so the debug flag cannot narrow type checking to build-path files — the user's expectation about limiting the check is incorrect.

Source

Thrown at packages/next/src/lib/verify-typescript-setup.ts:257

      strictRouteTypes
    )
    // Write out the necessary `next-env.d.ts` file to correctly register
    // Next.js' types:
    await writeAppTypeDeclarations({
      baseDir: dir,
      distDir,
      imageImportsEnabled: !disableStaticImages,
      hasPagesDir,
      hasAppDir,
      strictRouteTypes,
      typedRoutes,
    })

    let result
    if (shouldRunTypeCheck) {
      if (useTypeScriptCli) {
        if (debugBuildPaths) {
          log.warn(
            '`experimental.useTypeScriptCli` checks the complete TypeScript project; `--debug-build-paths` does not limit type checking.'
          )
        }

        const { runTypeCheckCli } =
          require('./typescript/runTypeCheckCli') as typeof import('./typescript/runTypeCheckCli')
        result = await runTypeCheckCli({
          baseDir: dir,
          tsConfigPath: resolvedTsConfigPath,
          tscPath: typeScriptPath,
          cacheDir,
          onFirstOutput: onFirstCliOutput,
        })
      } else {
        const { runTypeCheck } =
          require('./typescript/runTypeCheck') as typeof import('./typescript/runTypeCheck')
        // Install native bindings so that code frame rendering works in the worker
        const { installBindings } =

View on GitHub (pinned to 89d017eac4)

Solutions

1. Do not combine `--debug-build-paths` with `experimental.useTypeScriptCli` expecting scoped type checks; the whole project is checked.

When it happens

Trigger: Thrown at packages/next/src/lib/verify-typescript-setup.ts:255 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of vercel/next.js@89d017eac4 (2026-08-19). Data as JSON: /api/errors/eb2e08ec16c676c3. Report an issue: GitHub.