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.
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.
Before changing code, confirm where the circle occurs. Run the compiler with traceResolution and look for repeated entries:
npx tsc --traceResolution | rg "reference path" -nThe 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.
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:
// 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.
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:
{
"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.
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