> ## Documentation Index > Fetch the complete documentation index at: https://docs.fallow.tools/llms.txt > Use this file to discover all available pages before exploring further. # Debugging & troubleshooting > Trace export usage, diagnose false positives, and debug fallow's analysis pipeline with built-in tracing and performance profiling tools. When fallow reports something unexpected, built-in tracing and performance tools help you understand *why*. ## Tracing export usage Use `--trace FILE:EXPORT` to see the full usage chain for a specific export. Answers the question: "Who uses this export, and through which re-export paths?" ```bash theme={null} fallow dead-code --trace src/utils/format.ts:formatCurrency ``` ```bash title="$ fallow dead-code --trace src/utils/format.ts:formatCurrency" theme={null} UNUSED formatCurrency in src/utils/format.ts File: reachable Reason: No references found, export is unused ``` Prints every file that imports `formatCurrency`, including indirect usage through barrel re-exports. Use this when: * An export you expected to be used is reported as unused. * You want to understand which consumers depend on a symbol before removing it. * A re-export chain is not being resolved as expected. ## Tracing file edges Use `--trace-file PATH` to see all incoming and outgoing edges for a file in the module graph. Answers the question: "What does this file import, and what imports this file?" ```bash theme={null} fallow dead-code --trace-file src/components/Button.tsx ``` Shows every import the file makes and every file that imports from it. Use this when: * A file is reported as unused but you believe something should reference it. * You want to verify that a file is reachable from entry points. * You're investigating why a file's exports are all marked unused (maybe the file itself is unreachable). ## Tracing dependency usage Use `--trace-dependency PACKAGE` to find everywhere a package is used: imports, script binaries, and plugin detection. Answers the question: "Where is this dependency actually consumed?" ```bash theme={null} fallow dead-code --trace-dependency lodash ``` ```bash title="$ fallow dead-code --trace-dependency moment" theme={null} UNUSED moment (0 import(s)) ``` Reports all import sites, `package.json` script binary usage, and plugin-based detection for the given package. Use this when: * A dependency is reported as unused but you believe it's used in scripts or config files. * You want to audit which parts of your codebase depend on a specific package. * You're evaluating whether a dependency can be removed. ## Tracing duplication clones Use `dupes --trace FILE:LINE` to see all clone instances at a specific source location. Answers the question: "Where else does this duplicated code appear?" ```bash theme={null} fallow dupes --trace src/utils/validate.ts:42 ``` Shows every other location that shares the same clone group as the code at the given line. Use this when: * You want to find all copies of a duplicated block before refactoring. * You're deciding whether to extract a shared function or module. * A duplication finding seems incorrect and you want to inspect the matched instances. ## Performance profiling Use `--performance` to get a timing breakdown of each pipeline stage. Answers the question: "Where is fallow spending time?" ```bash theme={null} fallow dead-code --performance fallow dupes --performance ``` ```bash title="$ fallow dead-code --performance" theme={null} ┌─ Pipeline Performance ───────────────────────────── │ discover files: 12ms (847 files) │ plugins: 2ms │ parse/extract: 8ms (847 modules, 812 cached, 35 parsed) │ cache update: 2ms │ entry points: 1ms (388 entries) │ resolve imports: 3ms │ build graph: 1ms │ analyze: 2ms │ (other): 1ms │ ──────────────────────────────────────────────── │ TOTAL: 31ms └─────────────────────────────────────────────────── ``` The `(other)` row is the time inside `TOTAL` not attributed to a named stage (report assembly and inter-stage glue), so the sequential stages plus `(other)` sum to `TOTAL`. In combined mode (`fallow` with no subcommand) the `duplication` stage runs concurrently with the rest of the pipeline and is marked `(concurrent)`; it is shown for reference but is not part of the `TOTAL` sum, so it can legitimately exceed `TOTAL` when duplication detection runs longer than the dead-code pass. Use this when: * Analysis is slower than expected and you want to find the bottleneck. * You want to verify the cache is working (high hit rate means incremental runs are fast). * You're comparing performance across different configuration options. ### Parallel parse timing `parse/extract` runs across all cores. When the parse work was substantial and genuinely parallel, the line gains a `(parallel: ~Nms CPU)` suffix reporting the summed parse CPU across workers: ```bash title="$ fallow dead-code --performance (cold cache)" theme={null} │ parse/extract: 382ms (21033 modules) (parallel: ~594ms CPU) ``` Here the stage finished in 382ms of wall-clock but spent \~594ms of CPU across cores. When that figure is much larger than the wall-clock the stage is CPU-bound and benefits from more cores; when it is close to the wall-clock the stage is I/O-bound and extra threads will not help. The suffix is omitted on warm or trivial runs where there is little real parse work to report. In combined mode (`fallow` with no subcommand), the health breakdown reuses the discovered and parsed files from the dead-code pass, so its `discover files` and `parse/extract` rows read `(measured above)` and point you at the Pipeline Performance box where that cost is attributed. In `--format json`, the timings carry `parse_cpu_ms` (summed parse CPU) alongside the wall-clock fields, and the health timings carry `shared_parse`. These are observational and vary run to run, so do not gate CI on them. ## Cache behavior Fallow caches parsed AST data using bincode serialization with xxh3 hashing. On later runs, unchanged files load from cache instead of being re-parsed. ```bash theme={null} # Run with caching (default) fallow dead-code # Skip the cache entirely fallow dead-code --no-cache ``` Use `--no-cache` when: * You suspect stale cache entries are causing incorrect results. * You've changed fallow versions and want a clean analysis. * You're benchmarking full parse performance. The `--performance` flag shows cache statistics, including how many files were cache hits vs. misses. A high hit rate on incremental runs is expected. Only modified files need re-parsing. ## Common false positives ### Dynamic imports with runtime values Fallow resolves template literals and `import.meta.glob`, but fully dynamic imports like `import(variable)` can't be resolved statically. **Fix**: Add the target directory to `entry` in your config: ```jsonc theme={null} { "entry": ["src/plugins/*.ts"] } ``` ### Convention-based exports Some frameworks consume exports by naming convention rather than explicit imports. For example, Next.js `generateStaticParams` or Remix `loader` functions. **Fix**: Fallow's built-in plugins already handle most frameworks. If you're using a niche framework, create a [custom plugin](/frameworks/custom-plugins) or use `ignoreExports`: ```jsonc theme={null} { "ignoreExports": [ { "file": "src/routes/**/*.ts", "exports": ["loader", "action"] } ] } ``` ### Dependency injection frameworks DI containers (NestJS, Angular, InversifyJS) resolve dependencies at runtime via decorators and metadata. Fallow skips decorated class members by default, but injected services may look unused if they're only referenced via DI tokens. **Fix**: Add the DI-registered files as entry points, or suppress specific findings: ```typescript theme={null} // fallow-ignore-next-line unused-export export class UserService { /* ... */ } ``` If your codebase uses utility decorators that DO NOT imply reflective use (Playwright `@step`, internal `@measure`, `@log`, etc.), opt them out of the skip via `ignoreDecorators` so methods carrying ONLY those names are checked for usage normally: ```jsonc theme={null} // .fallowrc.json { "ignoreDecorators": ["@step"] } ``` A method carrying any decorator NOT in the list stays skipped, so `@step + @Inject` keeps the conservative DI-friendly behavior. ### Peer dependencies and optional dependencies Packages listed in `peerDependencies` or `optionalDependencies` are not analyzed by default since they may be provided by the consuming project. **Fix**: If fallow incorrectly flags these, add them to `ignoreDependencies`: ```jsonc theme={null} { "ignoreDependencies": ["react", "react-dom"] } ``` ### Config files not recognized as entry points If a config file (e.g., `tailwind.config.ts`) is reported as unused, its framework plugin may not be active. **Fix**: Run `fallow list` to check which plugins are active. If the relevant plugin isn't detected, add the config file to `entry`: ```jsonc theme={null} { "entry": ["tailwind.config.ts"] } ``` ## See also Overview of how fallow detects unused code. Full reference for the `fallow dead-code` command and all its flags. Suppress individual findings with inline comments.