Skip to main content
This guide covers common issues you might encounter when using Rev-dep and how to resolve them.

​
Installation Issues

​
Binary Not Found

Problem: After installing Rev-dep, the rev-dep command is not found.
If installed locally, use npx:
npx rev-dep --version
Or add to package.json scripts:
{
  "scripts": {
    "check:deps": "rev-dep config run"
  }
}
Ensure your global npm bin directory is in your PATH:
# Check npm global bin path
npm bin -g

# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH="$(npm bin -g):$PATH"

​
Version Mismatch

Problem: Different versions of Rev-dep across team members. Solution: Pin the version in package.json:
package.json
{
  "devDependencies": {
    "rev-dep": "2.0.0"  // Exact version, not ^2.0.0
  }
}

​
Configuration Issues

​
Config File Not Found

Problem: Rev-dep can’t find your configuration file. Solution: Ensure the config file is named correctly: 
rev-dep.config.json
rev-dep.config.jsonc
.rev-dep.config.json
.rev-dep.config.jsonc

​
Invalid JSON Schema

Problem: Configuration validation errors. Solution: Use the JSON schema for validation: 
{
  "configVersion": "1.6",
  "$schema": "https://github.com/jayu/rev-dep/blob/master/config-schema/1.6.schema.json?raw=true",
  "rules": []
}
Most editors will provide autocomplete and validation with the $schema field.

​
Config Version Mismatch

Problem: configVersion doesn’t match Rev-dep version. Solution: Use "configVersion": "1.6" for Rev-dep v2.x: 
{
  "configVersion": "1.6",
  "rules": []
}

​
Resolution Issues

​
Unresolved Imports

Problem: Rev-dep reports imports as unresolved that should work.
Ensure tsconfig.json is in the correct location:
rev-dep config run --tsconfig-json ./tsconfig.json
Or specify in config:
{
  "rules": [
    {
      "path": ".",
      "tsconfigJson": "./tsconfig.json"
    }
  ]
}
Verify exports field syntax:
package.json
{
  "exports": {
    ".": "./dist/index.js",  // Correct
    "./utils": "./dist/utils.js"  // Correct
  }
}
Set appropriate condition names:
rev-dep config run --condition-names=import,node,default
Add custom extensions to the config:
{
  "customAssetExtensions": ["glb", "mp3", "wasm"]
}
Suppress false positives:
{
  "rules": [
    {
      "unresolvedImportsDetection": {
        "enabled": true,
        "ignoreImports": ["@internal/*", "virtual:*"],
        "ignoreFiles": ["**/*.generated.ts"]
      }
    }
  ]
}

​
Monorepo Package Not Found

Problem: Cross-package imports not resolving in monorepo. Solution: Enable monorepo package following: 
{
  "rules": [
    {
      "path": ".",
      "followMonorepoPackages": true  // Follow all workspace packages
    }
  ]
}
Or specify packages explicitly: 
{
  "rules": [
    {
      "followMonorepoPackages": ["@myorg/utils", "@myorg/common"]
    }
  ]
}
Ensure workspace packages are properly declared in pnpm-workspace.yaml, package.json workspaces, or lerna config.

​
Performance Issues

​
Slow Execution

Problem: Rev-dep takes longer than expected.
1

Check file count

rev-dep list-cwd-files --count
If the count is very high, you may need to exclude files.
2

Use ignoreFiles

{
  "ignoreFiles": [
    "**/dist/**",
    "**/build/**",
    "**/.next/**",
    "**/coverage/**"
  ]
}
3

Optimize rule configuration

Use targeted entry points instead of broad patterns:
{
  "prodEntryPoints": [
    "src/index.ts"  // Specific file
  ]
}
Instead of:
{
  "prodEntryPoints": [
    "src/**/*.ts"  // Very broad
  ]
}
4

Profile execution

Use verbose mode to see what’s taking time:
rev-dep config run --verbose

​
Out of Memory

Problem: Node.js runs out of memory on large codebases. Solution: While Rev-dep is written in Go and doesn’t typically have memory issues, if you encounter problems: 
# Increase Node.js memory limit for the process manager
NODE_OPTIONS="--max-old-space-size=4096" rev-dep config run

​
Detection Issues

​
False Positives: Unused Exports

Problem: Rev-dep reports exports as unused when they are actually used.
Ensure all entry points are specified:
{
  "rules": [
    {
      "prodEntryPoints": ["src/index.ts", "src/cli.ts"],
      "devEntryPoints": ["scripts/**", "**/*.test.*"]
    }
  ]
}
Ignore exports in library entry points:
{
  "rules": [
    {
      "unusedExportsDetection": {
        "enabled": true,
        "ignoreFiles": ["src/index.ts", "src/public-api.ts"]
      }
    }
  ]
}
If exports are referenced in HTML, markdown, or other files:
{
  "rules": [
    {
      "unusedExportsDetection": {
        "enabled": true,
        "ignore": {
          "src/components/Widget.tsx": "*"
        }
      }
    }
  ]
}

​
False Positives: Unused Node Modules

Problem: Modules flagged as unused when they’re referenced in scripts or config. Solution: Configure where to look for module usage: 
{
  "rules": [
    {
      "unusedNodeModulesDetection": {
        "enabled": true,
        "pkgJsonFieldsWithBinaries": ["scripts", "lint-staged"],
        "filesWithBinaries": ["scripts/**/*.sh", ".husky/**"],
        "filesWithModules": [".storybook/main.ts", "vite.config.ts"]
      }
    }
  ]
}

​
False Negatives: Circular Dependencies

Problem: Circular dependencies exist but aren’t detected. Solution: Check if type imports are being excluded: 
# Don't ignore type imports for this check
rev-dep circular
If you’re using ignoreTypeImports: true, some circular dependencies involving types will be hidden: 
{
  "rules": [
    {
      "circularImportsDetection": {
        "enabled": true,
        "ignoreTypeImports": false  // Show all circular dependencies
      }
    }
  ]
}

​
Autofix Issues

​
Autofix Not Working

Problem: Running with --fix doesn’t apply changes.
1

Check autofix is enabled

{
  "rules": [
    {
      "unusedExportsDetection": {
        "enabled": true,
        "autofix": true  // Must be true
      }
    }
  ]
}
2

Verify check supports autofix

Only these checks support autofix:
  • unusedExportsDetection
  • orphanFilesDetection
  • importConventions
3

Check file permissions

Ensure files are writable:
ls -la src/

​
Autofix Creates Invalid Code

Problem: After autofix, code doesn’t compile. Solution: This is rare but can happen with:
  • Side-effect exports (exports used for their side effects, not imports)
  • Dynamic imports that Rev-dep can’t trace
Workaround: 
{
  "rules": [
    {
      "unusedExportsDetection": {
        "enabled": true,
        "autofix": false,  // Review manually first
        "ignore": {
          "src/side-effects.ts": "*"
        }
      }
    }
  ]
}

​
CI/CD Issues

​
Passing Locally, Failing in CI

Problem: Checks pass on local machine but fail in CI.
Pin versions in CI:
- uses: actions/setup-node@v3
  with:
    node-version: '18.x'  # Match local version
Ensure all dependencies are installed:
- run: npm ci  # Use ci, not install
- run: npm run check:deps
Set correct working directory:
- run: npm run check:deps
  working-directory: ./packages/frontend
CI might not have generated files:
- run: npm run build  # Generate files first
- run: npm run check:deps

​
CI Too Slow

Problem: Rev-dep takes too long in CI. Solutions:

Use caching

- uses: actions/cache@v3
  with:
    path: node_modules
    key: ${{ hashFiles('package-lock.json') }}

Optimize config

{
  "ignoreFiles": ["**/dist/**", "**/build/**"]
}

Use config over CLI

Config-based checks are 10x+ faster than running individual CLI commands

Reduce rule scope

Target specific packages instead of scanning everything

​
Getting Help

1

Enable verbose output

rev-dep config run --verbose --list-all-issues
2

Check the documentation

Review CLI reference and configuration docs
3

Search existing issues

GitHub Issues
4

Create a minimal reproduction

Isolate the problem in a small test case
5

Report the issue

Open a new issue with:
  • Rev-dep version (rev-dep --version)
  • Node version (node --version)
  • Operating system
  • Configuration file
  • Error output
  • Steps to reproduce
For questions and discussions, check the project’s GitHub repository or community forums.

Build docs developers (and LLMs) love

Get started for freeTalk to us