How to fix '--listFilesOnly' requires --listFiles in TypeScript

TypeScriptINTERMEDIATELOW

This TypeScript error occurs when you use the --listFilesOnly compiler flag without also enabling --listFiles. The --listFilesOnly option is dependent on --listFiles and requires it to be set first. The fix involves either adding --listFiles to your command or tsconfig.json, or using the correct standalone flag --listEmittedFiles instead.

What this error means

The "'--listFilesOnly' requires --listFiles" error appears when you try to use TypeScript's --listFilesOnly compiler option without first enabling the --listFiles option. These are related but distinct compiler flags with specific dependencies. --listFiles is a TypeScript compiler option that prints all files read during compilation, including library files and source files. This is useful for debugging which files TypeScript is including in your build. --listFilesOnly is a variant that depends on --listFiles being enabled. It's designed to work in conjunction with --listFiles, not as a standalone option. When you use --listFilesOnly without --listFiles, TypeScript cannot determine which files to list because the base listing functionality isn't active. The error indicates a misunderstanding of how these compiler options interact. TypeScript requires --listFiles to be enabled first to establish the file listing context, then --listFilesOnly can filter or modify that output.

How to fix "'--listFilesOnly' requires --listFiles"

1Add --listFiles flag to your tsc command

When using --listFilesOnly from the command line, you must also include --listFiles:

bash

# WRONG - missing --listFiles
tsc --listFilesOnly

# CORRECT - include both flags
tsc --listFiles --listFilesOnly

# You can also use the short form
tsc --listFiles --listFilesOnly src/**/*.ts

The order doesn't matter, but both flags must be present. After adding --listFiles, the command should execute successfully and list the files.

2Configure both flags in tsconfig.json

If you're configuring these options in your tsconfig.json file, set both properties:

json

{
  "compilerOptions": {
    "listFiles": true,
    "listFilesOnly": true,
    // other options...
  }
}

Then run TypeScript normally:

bash

npx tsc
# or
npm run build

With both flags enabled, TypeScript will list the files it processes during compilation.

3Use --listEmittedFiles instead for output files

If you want to see only the output files (JavaScript, declaration files, etc.) that TypeScript generates, use --listEmittedFiles instead. This is a standalone flag that doesn't require --listFiles:

bash

# Shows only generated output files
tsc --listEmittedFiles

# In tsconfig.json
{
  "compilerOptions": {
    "listEmittedFiles": true,
    // No need for listFiles or listFilesOnly
  }
}

Key differences:
- --listFiles: Shows all input files (source + libraries)
- --listFilesOnly: Requires --listFiles, shows filtered list
- --listEmittedFiles: Standalone, shows only output files (.js, .d.ts, etc.)

4Check TypeScript version and documentation

Verify your TypeScript version and consult the official documentation:

bash

# Check TypeScript version
npx tsc --version

# View help for listFiles options
npx tsc --help | grep -i list

Consult the TypeScript compiler options documentation:
- [TypeScript Compiler Options](https://www.typescriptlang.org/tsconfig)
- [Command Line Interface](https://www.typescriptlang.org/docs/handbook/compiler-options.html)

Note: In TypeScript 4.2+, consider using --explainFiles instead of --listFiles for more detailed information about why files were included.

5Update build scripts and CI/CD configurations

If you encounter this error in automated scripts or CI/CD pipelines, update the configuration:

bash

# Before (failing)
npm run build -- --listFilesOnly

# After (working)
npm run build -- --listFiles --listFilesOnly

For package.json scripts:

json

{
  "scripts": {
    "list-files": "tsc --listFiles --listFilesOnly",
    "list-emitted": "tsc --listEmittedFiles"
  }
}

Run the updated scripts:

bash

npm run list-files
npm run list-emitted

6Debug file inclusion with --explainFiles (TypeScript 4.2+)

For TypeScript 4.2 and later, use --explainFiles instead for better debugging:

bash

# Modern alternative to --listFiles
tsc --explainFiles

# Output shows why each file was included:
# - Because it matches include pattern in tsconfig.json
# - Because it's imported by another file
# - Because it's a library file
# - etc.

In tsconfig.json:

json

{
  "compilerOptions": {
    "explainFiles": true
  }
}

--explainFiles provides more context than --listFiles and doesn't have the dependency issues of --listFilesOnly. It's the recommended approach for debugging file inclusion in modern TypeScript projects.

Advanced notes

### Historical Context and Flag Evolution

The --listFiles and --listFilesOnly flags have an interesting history in TypeScript:

- TypeScript 1.5: --listFiles introduced as a debugging tool
- TypeScript 2.0: --listEmittedFiles introduced as a separate, standalone flag
- Undocumented feature: --listFilesOnly existed as a dependent flag but wasn't well-documented
- TypeScript 4.2: --explainFiles introduced as a modern replacement with better output

The confusion around --listFilesOnly stems from it being a "hidden" or poorly documented feature that depended on --listFiles. Many developers discovered it through trial and error or community knowledge sharing rather than official documentation.

### Alternative Debugging Approaches

Beyond compiler flags, consider these debugging techniques:

1. --traceResolution: Trace module resolution to see how TypeScript finds files

bash

npx tsc --traceResolution

2. --diagnostics: Show diagnostic information including file counts

bash

npx tsc --diagnostics

3. TypeScript Server Logs: In VS Code, enable TypeScript server logging:
- Open Command Palette (Cmd/Ctrl+Shift+P)
- Type "TypeScript: Open TS Server Log"
- Or set "typescript.tsserver.log": "verbose" in settings

### Understanding the Dependency Chain

The dependency between --listFiles and --listFilesOnly exists because:

1. --listFiles enables the file tracking system
2. --listFilesOnly queries that tracking system
3. Without --listFiles, there's no tracking system to query

This is similar to other dependent flags in TypeScript and other compilers where:
- A base flag enables a feature
- A modifier flag adjusts that feature
- The modifier cannot work without the base

### Migration to --explainFiles

If you're using --listFiles/--listFilesOnly for debugging, consider migrating to --explainFiles:

Benefits:
- Standalone flag (no dependencies)
- More informative output
- Shows reasoning for file inclusion
- Better integration with modern TypeScript features
- Actively maintained and documented

Migration example:

bash

# Old approach
tsc --listFiles --listFilesOnly

# New approach
tsc --explainFiles

The output format differs but provides more valuable information for debugging file inclusion issues.

How to fix '--listFilesOnly' requires --listFiles in TypeScript

What this error means

Typical symptoms

Common causes

How to fix "'--listFilesOnly' requires --listFiles"

Advanced notes

Related errors

Official resources & further reading