How to Fix: tsconfigPath is not supported by Turbopack

Turbopack fails fast when it encounters a tsconfigPath option it does not implement, which is why a project that works under the classic Next.js dev server can break immediately under npm run dev:turbo. The fix is usually not in your components at all—it is in how TypeScript configuration is being passed into Next.js tooling.

When this issue appears, the reproduction pattern is consistent: the app starts with Turbopack enabled, the browser opens, and the build crashes because Turbopack does not currently support overriding the TypeScript config file through tsconfigPath. In other words, the app is valid, but the selected bundler cannot honor that specific configuration feature yet.

Understanding the Root Cause

In Next.js, tsconfigPath allows the project to point tooling at a non-default TypeScript configuration file instead of the usual tsconfig.json. That can be useful in monorepos, split build targets, or setups where developers want one config for the editor and another for the app runtime.

The problem is that Turbopack does not support that override in the affected setup. It expects the standard resolution path and currently does not apply the custom TypeScript config location the same way the non-Turbopack pipeline does. As a result, aliases, compiler options, module resolution behavior, or inherited config values may not load correctly.

This is why the error is specifically tied to dev:turbo rather than regular development mode. The older bundling path and Turbopack do not yet have perfect feature parity, and tsconfigPath is one of those gaps.

Technically, the failure usually happens because one of these conditions is true:

• Next.js is configured to read a custom TypeScript config file via tsconfigPath.
• Turbopack starts and tries to resolve project settings without support for that override.
• Path aliases, baseUrl, or related compiler settings are then missing or inconsistent.
• The module graph breaks, causing the page to fail during compilation or routing.

Step-by-Step Solution

The most reliable solution is to stop depending on tsconfigPath when running under Turbopack and move the required TypeScript settings into the default tsconfig.json file that Turbopack expects.

1. Check whether your project is using tsconfigPath

Look in your Next.js configuration for a custom TypeScript config override.

/** @type {import('next').NextConfig} */
const nextConfig = {
  typescript: {
    tsconfigPath: './tsconfig.custom.json',
  },
}

module.exports = nextConfig

If you have something like this, it is the direct trigger for the issue under Turbopack.

2. Remove the tsconfigPath override

Update your next.config.js or next.config.mjs and remove the unsupported setting.

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Remove the unsupported typescript.tsconfigPath block
}

module.exports = nextConfig

3. Move the important compiler options into tsconfig.json

If your custom config was only there to define aliases or compiler behavior, merge those settings into the root tsconfig.json.

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

This is the key change: put the settings Turbopack needs into the default config file it already knows how to read.

4. If you need multiple configs, make tsconfig.json the Turbopack-facing entry point

Some teams still need extra TypeScript configs for tests, scripts, or editor workflows. In that case, use tsconfig.json as the main app config and let secondary configs extend it.

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Then let your other configs extend from the same base instead of trying to make Turbopack load a separate file through tsconfigPath.

5. Restart the dev server cleanly

After changing config files, stop the server fully and restart it.

rm -rf .next
npm run dev:turbo

If you are on Windows, remove the build output manually or use an equivalent command in PowerShell.

6. Verify alias resolution in the app

Test imports that rely on baseUrl or paths.

import Header from '@/components/Header'

If those imports now resolve correctly under Turbopack, the configuration mismatch has been fixed.

7. Temporary fallback if you cannot restructure config yet

If your project depends heavily on a custom TypeScript config and you cannot consolidate it immediately, use the non-Turbopack dev server until support lands.

npm run dev

This is not as fast, but it is the safest short-term workaround.

Common Edge Cases

• Monorepo path aliases: If aliases point outside the app directory, make sure the root tsconfig.json visible to Turbopack includes the correct baseUrl and paths mappings.
• Extends chains: A deeply nested extends setup can make it harder to see which file actually defines aliases. Flatten the important runtime options into the top-level app config if resolution still fails.
• Different test and app configs: Jest, Vitest, or ts-node may rely on a separate config. That is fine, but Turbopack still needs the app-facing defaults in tsconfig.json.
• Mixed jsconfig and tsconfig: If both files exist, remove ambiguity. Keep one primary config source for path mapping.
• Cached build output: Turbopack can appear broken even after fixing config if stale artifacts remain. Clear .next and restart.
• Editor works but app fails: Your IDE may understand a custom config independently, while Turbopack does not. Editor success does not prove bundler compatibility.

FAQ

Can I keep using a custom tsconfig file with Turbopack?

Not through tsconfigPath in the affected setup. The practical workaround is to make tsconfig.json the config Turbopack reads and move or extend your important options from there.

Why does this work with npm run dev but fail with npm run dev:turbo?

Because the classic Next.js development pipeline and Turbopack do not yet support exactly the same configuration surface. tsconfigPath is one of the unsupported differences here.

Do I need to remove all custom TypeScript configs?

No. You only need to ensure that the app settings required by Turbopack are available through the default tsconfig.json. Additional configs for tests or tooling can still exist.

If you want the project to be compatible today, the safest rule is simple: do not rely on tsconfigPath when running Turbopack. Put the runtime-critical TypeScript options in tsconfig.json, restart the dev server, and verify path aliases resolve normally.

For framework updates and future support changes, monitor the relevant Next.js discussions and release notes on the Next.js repository.