Troubleshooting

We can distinguish two types of issues:

• Lint issues reported by Knip
• Exceptions thrown by Knip

Also see the debug and trace options below that can help to troubleshoot issues.

Note

The JavaScript/TypeScript ecosystem has a vast amount of frameworks and tools, and even more ways to configure those. Files and dependencies can be referenced in many ways, not just through static import statements. In short: “it’s complicated”. Knip and documentation are always a work in progress.

If it doesn’t come your way at the first try, please understand this also shows the dynamic and innovative nature of the ecosystem. Often only small changes go a long way towards success. When a bit of configuration doesn’t improve things, consider opening an issue and/or ask away on Discord. With the help of the community (that’s you!) we can improve Knip for everyone and make project maintenance easier and more fun!

Lint issues reported by Knip

Knip reports lint issues in your codebase. See handling issues to deal with the reported issues.

If Knip reports false positives and you’re considering filing a GitHub issue, please do! It’ll make Knip better for everyone. Please read issue reproduction first.

Exit code 1 indicates a successful run, but lint issues were found.

Exceptions thrown by Knip

Knip may throw an exception, resulting in an unsuccessful run.

See known issues as it may be listed there and a workaround may be available. If it isn’t clear what’s throwing the exception, try another run with --debug to locate the cause of the issue with more details.

If Knip throws an exception and you’re considering filing a GitHub issue, please do! It’ll make Knip better for everyone. Please read issue reproduction first.

Exit code 2 indicates an exception was thrown by Knip.

Debug

To better understand why Knip reports what it does, run it in debug mode by adding --debug to the command:

knip --debug

This will give a lengthy output, including:

• Included workspaces
• Used configuration per workspace
• Enabled plugins per workspace
• Glob patterns and options followed by matching file paths
• Plugin config file paths and found dependencies per plugin
• Compiled non-standard source files

Trace

Use --trace to see where all exports are used. Or be more specific:

• Use --trace-file [path] to output this only for the given file.
• Use --trace-export [name] to output this only for the given export name.
• Use both to trace a specific named or default export of a certain file.

This works across re-exports, barrel files and workspaces. Here’s an example screenshot:

It’s like a reversed module graph. Instead of traversing imports it goes in the opposite direction and shows where exports are imported.

Legend

	Description
✓	Contains import and reference to the export
x	Is not imported
◯	Entry file

Opening an issue

If you want to open an issue, please see issue reproduction.

Understanding Knip

Looking to better understand how Knip works? The entry files and plugins explanations cover two core concepts. After this you might want to check out features like production mode and monorepos & workspaces.

In a more general sense, Why use Knip? explains what Knip can do for you.

Asking for help

If you can’t find your answer in any of the aforementioned resources, feel free to open an issue on GitHub or discuss it in the Discord channel.