How to fix Project reference is stale, run 'tsc --build' in TypeScript

What this error means

The "Project reference is stale" error appears when you're using TypeScript's project references feature and a referenced project has changed since it was last built. TypeScript project references allow you to structure large codebases into multiple TypeScript projects that depend on each other. When Project A references Project B, TypeScript needs to know the compiled output and type information from Project B. If you modify files in Project B but don't rebuild it, Project A will see outdated type information, leading to this error. This is a safety feature that ensures type consistency across your entire codebase. TypeScript detects when referenced projects have been modified and requires a rebuild before continuing compilation.

Typical symptoms

• Compilation fails with "Project reference is stale, run tsc --build" error
• Error occurs after modifying files in a referenced TypeScript project
• TypeScript server in IDE shows errors for imports from referenced projects
• Build process works initially but fails after making changes to dependencies
• Error appears even when the modified files seem unrelated to the current project

Common causes

1. Modified source files in a referenced TypeScript project without rebuilding
2. Deleted or renamed files in a referenced project
3. Changed tsconfig.json settings in a referenced project
4. Using `tsc` instead of `tsc --build` to compile projects with references
5. Outdated .tsbuildinfo files from previous builds
6. Manual editing of compiled output files (.d.ts, .js) instead of source files

How to fix "Project reference is stale, run 'tsc --build'"

# Rebuild all projects in the solution
tsc --build

# Or with shorter syntax
tsc -b

# If you have a specific tsconfig.json for building
tsc --build tsconfig.json

# For incremental builds (faster)
tsc --build --incremental

# Clean all build outputs
tsc --build --clean

# Then rebuild
tsc --build

# Or combine in one command
tsc --build --clean --force

// tsconfig.json (root or main project)
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist"
  },
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/utils" }
  ]
}

// packages/core/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "../../dist/core"
  }
}

// packages/utils/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "../../dist/utils"
  }
}

// package.json
{
  "scripts": {
    "build": "tsc --build",
    "build:clean": "tsc --build --clean",
    "build:watch": "tsc --build --watch",
    "build:incremental": "tsc --build --incremental",
    "clean": "tsc --build --clean"
  }
}

npm run build        # Standard build
npm run build:watch  # Watch mode for development
npm run clean        # Clean build artifacts

{
  "scripts": {
    "build": "npm run build --workspaces",
    "build:packages": "npm run build --workspace=packages/*"
  }
}

// WRONG - missing composite
{
  "compilerOptions": {
    "declaration": true
  }
}

// CORRECT
{
  "compilerOptions": {
    "composite": true,
    "declaration": true
  }
}

// WRONG - projects output to same directory
{
  "compilerOptions": {
    "outDir": "../dist"
  }
}

// CORRECT - unique output directories
{
  "compilerOptions": {
    "outDir": "../dist/core"
  }
}

// WRONG - references tsconfig.json file directly
{
  "references": [
    { "path": "./packages/core/tsconfig.json" }
  ]
}

// CORRECT - references directory
{
  "references": [
    { "path": "./packages/core" }
  ]
}

# Watch all projects
tsc --build --watch

# Watch with specific tsconfig
tsc --build tsconfig.json --watch

# Watch with incremental builds
tsc --build --watch --incremental

# In package.json scripts
{
  "scripts": {
    "dev": "tsc --build --watch",
    "dev:incremental": "tsc --build --watch --incremental"
  }
}

Advanced notes

# Verbose output showing build steps
tsc --build --verbose

# List all project references
tsc --build --dry

# Show dependency graph
tsc --build --listFiles

# Check specific project
tsc --project packages/core --showConfig

Frequently asked questions

What does "Project reference is stale, run 'tsc --build'" mean?

The "Project reference is stale" error appears when you're using TypeScript's project references feature and a referenced project has changed since it was last built. TypeScript project references allow you to structure large codebases into multiple TypeScript projects that depend on each other. When Project A references Project B, TypeScript needs to know the compiled output and type information from Project B.

How do I fix "Project reference is stale, run 'tsc --build'"?

This TypeScript error occurs when using project references and the referenced project has been modified without rebuilding. TypeScript needs to rebuild the referenced project to ensure type information is up-to-date. Running tsc --build or tsc -b will rebuild all referenced projects.

What causes "Project reference is stale, run 'tsc --build'"?

Modified source files in a referenced TypeScript project without rebuilding Deleted or renamed files in a referenced project Changed tsconfig.json settings in a referenced project

Is the "Project reference is stale, run 'tsc --build'" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• Property 'x' cannot be accessed on type 'never'

  How to fix "Property cannot be accessed on type never" in TypeScript

  MEDIUM

• Project 'X' cannot reference itself

  How to fix 'Project cannot reference itself' error in TypeScript

  MEDIUM

• The property 'X' cannot be imported with import syntax

  How to fix "The property cannot be imported with import syntax" in TypeScript

  MEDIUM

• Project reference path must point to tsconfig.json

  How to fix "Project reference path must point to tsconfig.json" in TypeScript

  MEDIUM

• Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

  How to fix "Cannot find name 'process'" in TypeScript

  MEDIUM

• Module has no exported member 'X'

  How to fix 'Module has no exported member X' error in TypeScript

  MEDIUM

Official resources & further reading

• 📚TypeScript Official Documentation
• 📖
  TypeScript Handbook - Project References(Official Docs)
• 📖
  TypeScript Handbook - Base tsconfig.json(Official Docs)
• 📖
  TypeScript TSConfig - composite(Official Docs)
• 🐙
  TypeScript GitHub - Project Reference Stale Issues(GitHub)
• TypeScript - Build Mode for TypeScript
• Stack Overflow - TypeScript Project References
• LogRocket - Using TypeScript Project References