How to fix Cannot use '--tsBuildInfoFile' without '--incremental' or '--composite' in TypeScript

TypeScriptBEGINNERMEDIUMUpdated Dec 11, 2025· 205 views

The TypeScript compiler only allows you to specify a custom tsBuildInfoFile when incremental or composite compilation is active. This error pops up whenever you try to cache compilation metadata without enabling either of those modes.

Quick fix

Fixes Cannot use '--tsBuildInfoFile' without '--incremental' or '--composite'

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./.cache/my-project.tsbuildinfo",
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}
  1. Enable incremental compilation in tsconfig
  2. Use composite mode for referenced projects
  3. Pass both flags when invoking tsc directly
  4. Clean stale caches and verify the file path
typescript — error
{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./.cache/my-project.tsbuildinfo",
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}
Cannot use '--tsBuildInfoFile' without '--incremental' or '--composite'

What this error means

Setting tsBuildInfoFile tells tsc to read and write a .tsbuildinfo cache, but the compiler only generates that cache when incremental builds or composite projects are turned on. When neither option is set, the CLI cannot honor --tsBuildInfoFile because there is no incremental build state to persist. TypeScript stops early with this error to prevent a useless cache file and to signal that you must opt into caching explicitly.

Typical symptoms

  • tsc immediately fails before emitting files with the error message and a TS identifier
  • Build scripts crash when they pass --tsBuildInfoFile on the command line without incremental flags
  • .tsbuildinfo files are not created and the compiler hangs on the configuration step
  • CI jobs that set tsBuildInfoFile to share caches across steps fail even though the code would compile in plain mode
  • Any watch mode or incremental build task that expects tsbuildinfo can never start because the compiler rejects the flag

Common causes

  1. tsconfig.json defines tsBuildInfoFile but does not set compilerOptions.incremental or composite
  2. Calling tsc --tsBuildInfoFile from npm scripts or CI without also passing --incremental or --composite
  3. Copying a shared tsconfig template that hard-codes tsBuildInfoFile even for projects that always do clean builds
  4. Relying on project references without turning on composite, so incremental mode never activates
  5. Typos or mismatched casing cause TypeScript to ignore incremental/composite options, so tsBuildInfoFile becomes orphaned

How to fix "Cannot use '--tsBuildInfoFile' without '--incremental' or '--composite'"

1Enable incremental compilation in tsconfig

Turn on incremental builds wherever you want to cache compiler metadata. Add both incremental: true and the tsBuildInfoFile path so TypeScript can keep the cache out of the default output folder.

json
{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./.cache/my-project.tsbuildinfo",
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

Once incremental is enabled, the compiler happily writes the .tsbuildinfo file and the error disappears.

2Use composite mode for referenced projects

Project references require composite: true, which implicitly turns on incremental builds and allows tsBuildInfoFile. Each referenced project must emit declarations, so combine the settings carefully:

json
{
  "compilerOptions": {
    "composite": true,
    "tsBuildInfoFile": "../.cache/shared.tsbuildinfo",
    "declaration": true,
    "outDir": "./lib"
  },
  "references": [
    { "path": "../shared" },
    { "path": "../utils" }
  ]
}

The composite flag guarantees the incremental cache exists, so TypeScript lets tsBuildInfoFile stay in the config.

3Pass both flags when invoking tsc directly

If you call the compiler from the CLI, mirror the incremental mode flags so the tsBuildInfoFile flag is valid:

bash
npx tsc --incremental --tsBuildInfoFile .cache/app.tsbuildinfo
npx tsc --composite --tsBuildInfoFile .cache/app.tsbuildinfo   # for build mode

You can override tsBuildInfoFile from the CLI while keeping the config minimal. Always include either --incremental or --composite on the same command line.

4Clean stale caches and verify the file path

Remove old cache files and make sure the directory exists:

bash
rm -f .cache/*.tsbuildinfo
mkdir -p .cache
npx tsc --incremental --tsBuildInfoFile .cache/app.tsbuildinfo

Also add .tsbuildinfo to .gitignore to prevent accidental commits. The compiler must write to a location it can reach, so create the folder if it was missing.

Advanced notes

## Why tsBuildInfoFile requires incremental/composite

The tsBuildInfoFile option changes only where TypeScript stores the build cache. Without incremental or composite, no cache exists, so the option would point to an unused file. The compiler therefore rejects it at startup.

When you enable composite: true, TypeScript automatically sets incremental behind the scenes and enforces declaration: true. Composite projects are also required for tsc --build to understand dependencies between multiple tsconfig.json files.

If you need fine-grained build caches per environment (CI, dev, watch), point tsBuildInfoFile into a shared folder, but keep incremental/composite on so TypeScript can keep the cache consistent between runs.

Frequently asked questions

What does "Cannot use '--tsBuildInfoFile' without '--incremental' or '--composite" mean?
tsbuildinfo cache, but the compiler only generates that cache when incremental builds or composite projects are turned on. When neither option is set, the CLI cannot honor --tsBuildInfoFile because there is no incremental build state to persist. TypeScript stops early with this error to prevent a useless cache file and to signal that you must opt into caching explicitly.
How do I fix "Cannot use '--tsBuildInfoFile' without '--incremental' or '--composite"?
The TypeScript compiler only allows you to specify a custom tsBuildInfoFile when incremental or composite compilation is active. This error pops up whenever you try to cache compilation metadata without enabling either of those modes.
What causes "Cannot use '--tsBuildInfoFile' without '--incremental' or '--composite"?
tsconfig.json defines tsBuildInfoFile but does not set compilerOptions.incremental or composite Calling tsc --tsBuildInfoFile from npm scripts or CI without also passing --incremental or --composite Copying a shared tsconfig template that hard-codes tsBuildInfoFile even for projects that always do clean builds
Is the "Cannot use '--tsBuildInfoFile' without '--incremental' or '--composite" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading