How to fix Circular reference in triple-slash directives in TypeScript

TypeScriptINTERMEDIATEHIGHUpdated Dec 11, 2025· 93 views

Triple-slash directives let an outFile or pre-compiled bundle control the ordering of files. When those directives reference each other in a loop, TypeScript cannot decide which file should be emitted first and it stops with this diagnostic.

Quick fix

Fixes Circular reference in triple-slash directives

npx tsc --traceResolution | rg "reference path" -n
  1. Trace the triple-slash dependency graph
  2. Stop referring back with triple slashes
  3. Reorder or split triple-slash chains when bundling with outFile
typescript — error
npx tsc --traceResolution | rg "reference path" -n
Circular reference in triple-slash directives
shell
npx tsc --traceResolution | rg "reference path" -n

What this error means

Triple-slash references form a directed graph that determines the order of files when you're compiling with "outFile"/`prepend` bundles or when a tsconfig project opts out of implicit referencing. TypeScript walks that graph before emitting code, so a cycle (A references B and B references A, even indirectly) makes the order ambiguous. Instead of guessing, the compiler raises "Circular reference in triple-slash directives" to force you to break the cycle or rely on modules/imports for dependency order.

Typical symptoms

  • tsc aborts with 'Circular reference in triple-slash directives' instead of producing JavaScript
  • Error appears only when you compile with --outFile, --prepend, or files that use triple-slash directives instead of ES module imports
  • The same files can compile if you remove redundant references or convert them into imports
  • tsc --traceResolution shows the same files referenced repeatedly before the error appears
  • Builds using project references (tsconfig references or composite projects) also break when a triple-slash cycle is present

Common causes

  1. Two or more files use `/// <reference path="./Other.ts" />` to declare a dependency cycle that cannot be linearized
  2. Some files opt into explicit triple-slash ordering while others rely on implicit module resolution, which can reintroduce the cycle when the compiler merges the graphs
  3. OutFile/Prepend builds enumerate every triple-slash directive in the supplied file list; an accidental back-reference creates a circular graph
  4. Legacy Visual Studio projects that still rely on `/// <reference>` chains often mix generated declaration order in ways that trigger the cycle
  5. Mixing triple-slash references with project references (tsconfig `references`) without carefully controlling the output order can resurrect the cycle

How to fix "Circular reference in triple-slash directives"

1Trace the triple-slash dependency graph

Before changing code, confirm where the circle occurs. Run the compiler with traceResolution and look for repeated entries:

bash
npx tsc --traceResolution | rg "reference path" -n

The output shows the explicit references that tsc is walking; the file that appears twice with no intervening termination is part of the cycle. You can also open the file list and sketch the directed graph to spot the loop.

2Stop referring back with triple slashes

Remove the explicit reference on one side of the cycle or replace it with a normal import/export. For example, if A.ts and B.ts each reference the other with triple slashes, drop /// <reference path="./B.ts" /> from A.ts and use an ES module import instead:

ts
// B.ts
export function helper() {}

// A.ts
import { helper } from "./B";

If your tsconfig still targets an outFile, keep the files in the required order via the files array or project references instead of triple-slash directives. After the change, run npx tsc (or your build script) to confirm the fatal error disappears.

3Reorder or split triple-slash chains when bundling with outFile

When you truly need triple-slash directives (e.g. outFile with global scripts), break the cycle by splitting the bundle or creating a separate entry that imports the other side rather than referencing it:

json
{
  "compilerOptions": {
    "outFile": "./dist/bundle.js",
    "module": "none"
  },
  "files": [
    "./src/defs.d.ts",
    "./src/core.ts",
    "./src/extension.ts"
  ]
}

Ensure the files list is linear and remove any /// <reference path> that would cause a jump back. If the dependency is still cyclical, split that file into two so the combined graph is acyclic. After the tsconfig edit, npx tsc --build or npm run build should succeed without the circular-reference diagnostic.

Frequently asked questions

What does "Circular reference in triple-slash directives" mean?
Triple-slash references form a directed graph that determines the order of files when you're compiling with "outFile"/prepend bundles or when a tsconfig project opts out of implicit referencing. TypeScript walks that graph before emitting code, so a cycle (A references B and B references A, even indirectly) makes the order ambiguous. Instead of guessing, the compiler raises "Circular reference in triple-slash directives" to force you to break the cycle or rely on modules/imports for dependency order.
How do I fix "Circular reference in triple-slash directives"?
Triple-slash directives let an outFile or pre-compiled bundle control the ordering of files. When those directives reference each other in a loop, TypeScript cannot decide which file should be emitted first and it stops with this diagnostic.
What causes "Circular reference in triple-slash directives"?
Two or more files use /// <reference path="./Other.ts" /> to declare a dependency cycle that cannot be linearized Some files opt into explicit triple-slash ordering while others rely on implicit module resolution, which can reintroduce the cycle when the compiler merges the graphs OutFile/Prepend builds enumerate every triple-slash directive in the supplied file list; an accidental back-reference creates a circular graph
Is the "Circular reference in triple-slash directives" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading