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.
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.
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.
{
"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.
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:
{
"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.
If you call the compiler from the CLI, mirror the incremental mode flags so the tsBuildInfoFile flag is valid:
npx tsc --incremental --tsBuildInfoFile .cache/app.tsbuildinfo
npx tsc --composite --tsBuildInfoFile .cache/app.tsbuildinfo # for build modeYou can override tsBuildInfoFile from the CLI while keeping the config minimal. Always include either --incremental or --composite on the same command line.
Remove old cache files and make sure the directory exists:
rm -f .cache/*.tsbuildinfo
mkdir -p .cache
npx tsc --incremental --tsBuildInfoFile .cache/app.tsbuildinfoAlso 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.
## 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.
Function expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript
Type narrowing from typeof check produces 'never'
How to fix "Type narrowing produces never" in TypeScript
Type parameter 'T' has conflicting constraints
How to fix "Type parameter has conflicting constraints" in TypeScript