Skip to content

Troubleshooting

We can distinguish two types of issues:

Issues reported by Knip

This indicates a successful run, but there are unused items. Continue with handling issues to deal with unused items reported by Knip.

Exceptions thrown by Knip

Knip (or one of its plugins loading a configuration file) may throw an error, resulting in an unsuccessful run. You might be encountering a known issue.

Add --debug to the command for more error details to better locate the cause of the error.

Debug

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

Terminal window
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 exports are used.

  • 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 be more specific, this is useful e.g. for tracing only the default export of a certain file.

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

trace

Legend

Description
Contains import and reference to the export
Entry file

Minimal reproduction

If you encounter an issue or false positives when running Knip, you can open an issue on GitHub. Depending on the type of issue, you might be asked to create a minimal reproduction: only the code and configuration required to demonstrate the issue.

A convenient way to do so is by starting with one of these templates in CodeSandbox or StackBlitz:

Template
BasicCodeSandboxStackBlitz
MonorepoCodeSandboxStackBlitz

Other solutions may work well too. For instance, many people choose to create a small repository on GitHub. The goal is to have an easy and common understanding and 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.

ISC License © 2024 Lars Kappert