Troubleshooting Guide

This guide helps you quickly resolve common issues with claudelint.

Common Errors by Category

CLAUDE.md Issues

File exceeds size limit

Cause: Your CLAUDE.md file exceeds the recommended 40KB limit (configurable). Files this large should be split into smaller, focused files using @import.

Solutions:

1. Split content into smaller files and use @import:

   <!-- CLAUDE.md -->
   
   @import ./docs/architecture.md
   @import ./docs/api-reference.md

2. Remove embedded data (base64 images, large code blocks)

3. Use external links instead of inline content

4. Check for accidentally included binary data

See: claude-md-size

Imported file not found

Cause: @import statement references a file that doesn't exist.

Example:

@import ./nonexistent-file.md

Solutions:

1. Check file path is correct (relative to CLAUDE.md)
2. Verify file exists in the repository
3. Check for typos in filename
4. Ensure proper file extension (.md, .txt, etc.)

See: claude-md-import-missing

Circular import detected

Cause: File A imports File B, which imports File A (directly or indirectly).

Example:

<!-- CLAUDE.md -->

@import ./docs/setup.md

<!-- setup.md -->

@import ../CLAUDE.md <!-- Circular! -->

Solutions:

1. Restructure imports to be hierarchical (tree, not graph)
2. Extract shared content to a common file
3. Remove redundant imports

See: claude-md-import-circular

Skills Issues

Missing version field

Cause: SKILL.md missing required version field in frontmatter.

Example:

---
name: my-skill
description: Does something
---

Solution:

Add version to frontmatter:

---
name: my-skill
description: Does something
version: 1.0.0
---

Auto-fix: Run claudelint check-all --fix to automatically add version: "1.0.0".

See: skill-missing-version

Name-directory mismatch

Cause: Skill's name field doesn't match its directory.

Example:

.claude/skills/user-auth/SKILL.md

Frontmatter:
name: authentication  <!-- Doesn't match directory 'user-auth' -->

Solutions:

1. Rename directory to match skill name
2. Update skill name in frontmatter to match directory

See: skill-name-directory-mismatch

Missing shebang

Cause: Executable .sh file doesn't start with #!/bin/bash or similar.

Solution:

Add shebang to first line of script:

#!/usr/bin/env bash

# Rest of script...

Auto-fix: Run claudelint check-all --fix to automatically add shebang.

See: skill-missing-shebang

Settings Issues

Referenced path not found

Cause: Settings file references a path that doesn't exist.

Example:

{
  "commandPaths": ["./nonexistent-commands"]
}

Solutions:

1. Create the missing directory/file
2. Fix the path in settings.json
3. Remove the reference if no longer needed

See: settings-file-path-not-found

Hooks Issues

Hook script not found

Cause: hooks.json references a script that doesn't exist.

Example:

{
  "SessionStart": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/missing-script.sh"
        }
      ]
    }
  ]
}

Solutions:

1. Create the missing script
2. Fix the path in hooks.json
3. Verify path is relative to .claude/hooks.json

See: hooks-missing-script

Frequently Asked Questions

Configuration

Disable a rule

Set the rule to "off" in .claudelintrc.json:

{
  "rules": {
    "skill-missing-changelog": "off"
  }
}

See Configuration Guide for details.

Disable for one file

Use inline disable comments:

<!-- claudelint-disable-next-line import-missing -->

@import optional-file.md

See Inline Disables for details.

Config file location

claudelint searches for config files starting from the current directory and moving up:

Supported files:

• .claudelintrc.json
• package.json (with claudelint key)

Place it in your project root for best results.

View resolved config

Run:

claudelint print-config

This shows the resolved configuration with all defaults.

Validation

Errors in node_modules

Add a .claudelintignore file:

node_modules/
dist/
coverage/

See Configuration - Ignoring Files for details.

Run a single validator

Yes, use specific commands:

claudelint validate-claude-md
claudelint validate-skills
claudelint validate-settings

See CLI Reference for all commands.

Detailed error output

Use the --verbose flag:

claudelint check-all --verbose

This shows timing information and additional context.

Auto-Fix

Fixable rules

Run:

claudelint list-rules --fixable

This shows all rules that support auto-fix.

Preview fixes

Use --fix-dry-run:

claudelint check-all --fix-dry-run

This shows what would be fixed without making changes.

Fix only errors

claudelint check-all --fix --fix-type errors

See Auto-fix Guide for details.

Performance

Speed up validation

1. Use caching (enabled by default):

   claudelint check-all  # Uses cache

2. Add ignore patterns in .claudelintignore:

   node_modules/
   dist/
   *.log

3. Check timing to find slow validators:

   claudelint check-all --verbose

See CLI Reference for cache details.

Clear the cache

claudelint cache-clear

Run this after upgrading claudelint or changing config.

Installation

Command not found

Global install:

npm install -g claude-code-lint

yarn global add claude-code-lint

pnpm add -g claude-code-lint

Then verify: claudelint --version

Project install:

npm install --save-dev claude-code-lint

yarn add --dev claude-code-lint

pnpm add -D claude-code-lint

Then verify: npx claude-code-lint --version

Or use full path:

./node_modules/.bin/claudelint --version

Permission denied

macOS/Linux:

sudo npm install -g claude-code-lint

Or configure npm to install without sudo:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g claude-code-lint

Error Message Guide

Understanding error output

claudelint error messages follow this format:

/path/to/file.md (1 error)
  12  error  Referenced skill not found: authentication  skill-referenced-file-not-found

1 problem (1 error, 0 warnings)

Breaking it down:

• Path: /path/to/file.md (1 error) - File with the issue and count
• Line: 12 - Line number (0 for file-level issues)
• Severity: error or warning
• Message: Referenced skill not found: authentication - What's wrong
• Rule ID: skill-referenced-file-not-found - Which rule triggered this

Looking up rule details

To see full documentation for a rule:

1. Note the rule ID from the error (e.g., skill-referenced-file-not-found)
2. Browse the Rules Reference in the sidebar
3. Or use the CLI:

claudelint check-all --explain

Configuration Issues

Config file not found

Error: No configuration found

Solutions:

1. Create .claudelintrc.json in project root:

   claudelint init

2. Or add config to package.json:

   {
     "claudelint": {
       "rules": {
         "skill-missing-version": "error"
       }
     }
   }

3. Or specify config path:

   claudelint check-all --config /path/to/config.json

Rules not being applied

Error: Rules show in list-rules but don't trigger

Solutions:

1. Verify config syntax:

   cat .claudelintrc.json | jq

2. Check rule names match exactly:

   {
     "rules": {
       "skill-missing-version": "error" // Correct
       // "skillMissingVersion": "error"  // Wrong (not kebab-case)
     }
   }

3. View resolved config:

   claudelint print-config

JSON parsing error

Error: Unexpected token } in JSON

Solution:

Validate your JSON syntax:

cat .claudelintrc.json | jq

Common mistakes:

• Trailing commas
• Missing quotes around keys
• Incorrect string escaping

CI/CD Issues

Unexpected exit codes

Exit codes:

• 0 - Success (no violations)
• 1 - Linting issues found (errors or warnings)
• 2 - Fatal error (crash, invalid config)

Usage in CI:

# Most CI systems check for non-zero exit
claudelint check-all || exit 1

See CLI Reference - Exit Codes for details.

Hook not running at session start

Solutions:

1. Verify .claude/hooks.json (or .claude/hooks/hooks.json) exists

2. Validate: claudelint validate-hooks

3. Check event name is "SessionStart" (capital S)

4. Test command manually first:

   claudelint check-all --format compact

Cache Issues

Stale results after upgrade

Symptom: After upgrading claudelint, you still see old validation results or missing new rules.

Cause: The cache stores results keyed by claudelint version and build fingerprint. In rare cases (e.g., reinstalling the same version), stale entries may persist.

Solution:

claudelint cache-clear

This removes the entire .claudelint-cache/ directory. The next run rebuilds the cache from scratch.

Cache not invalidating

Symptom: You edited a file but claudelint still reports old results.

Cause: Cache invalidation is mtime-based. If a file's modification time didn't change (e.g., git checkout restoring a file to its previous state, or a tool that preserves timestamps), the cache considers it unchanged.

Solutions:

1. Clear the cache:

   claudelint cache-clear

2. Or bypass the cache for a single run:

   claudelint check-all --no-cache

3. Touch the file to update its mtime:

   touch CLAUDE.md

Large cache directory

Symptom: .claudelint-cache/ accumulates many files over time.

Cause: Each unique combination of validator + config + version creates a separate cache entry. Old entries from previous versions are not automatically pruned.

Solution:

claudelint cache-clear

Add .claudelint-cache/ to your .gitignore to keep it out of version control:

.claudelint-cache/

Auto-fix not applying

Symptom: Running --fix reports issues but doesn't modify files.

Cause: Caching is automatically disabled during --fix and --fix-dry-run to ensure fixes are always applied. If fixes still aren't applying, the issue is likely that the rule doesn't support auto-fix.

Solution:

Check which rules are fixable:

claudelint list-rules --fixable

Only rules with fixable: true will apply changes with --fix.

Cache CLI reference

Command / Flag	Description
claudelint cache-clear	Remove all cached results
--no-cache	Disable caching for this run
--cache-location <path>	Use a custom cache directory (default: .claudelint-cache)

See CLI Reference - Cache Management for full details.

Custom Rules Issues

Custom rule not loading

Error: Failed to load custom rule

Solutions:

1. Verify file is in .claudelint/rules/ directory

2. Check file extension is .ts or .js (not .d.ts, .test.ts)

3. Ensure a named rule export is used:

   import type { Rule } from 'claude-code-lint';
   
   export const rule: Rule = {
     meta: {
       /* ... */
     },
     validate: async (context) => {
       /* ... */
     },
   };

4. Check for syntax errors in the rule file

See Custom Rules Guide for details.

Custom rule not executing

Solutions:

1. Check rule is enabled in .claudelintrc.json:

   {
     "rules": {
       "my-custom-rule": "error"
     }
   }

2. Verify context.report() is being called

3. Add debug logging:

   validate: async (context) => {
     console.log('Validating:', context.filePath);
     // ...
   };

Environment Variables

Update notification in CI

Symptom: You see "Update available: X.X.X -> Y.Y.Y" in CI output.

Cause: claudelint checks for newer versions once every 24 hours.

Solution:

Set one of these environment variables to suppress notifications:

# In your CI config
CI=true claudelint check-all

# Or explicitly
NO_UPDATE_NOTIFIER=1 claudelint check-all

No color in CI

Symptom: Output is plain text without color formatting.

Cause: Color is auto-detected based on TTY status. CI environments typically don't have a TTY.

Solution:

Force color output:

FORCE_COLOR=1 claudelint check-all

# Or use the flag
claudelint check-all --color

Unwanted color in logs

Symptom: ANSI escape codes appearing in redirected output or log files.

Solution:

Disable color output:

NO_COLOR=1 claudelint check-all

# Or use the flag
claudelint check-all --no-color

stdin and Editor Integration

stdin not reading input

Symptom: claudelint check-all --stdin hangs or times out.

Cause: stdin mode expects piped input. Running it interactively (without piped data) will timeout after 5 seconds.

Solution:

Pipe content into stdin:

cat CLAUDE.md | claudelint check-all --stdin --stdin-filename CLAUDE.md

No matching validator

Symptom: Exit code 2 with error about no matching validator.

Cause: The --stdin-filename doesn't match any validator's file patterns.

Solution:

Use a filename that matches a known pattern:

# CLAUDE.md files
cat content.md | claudelint check-all --stdin --stdin-filename CLAUDE.md

# Settings
cat settings.json | claudelint check-all --stdin --stdin-filename .claude/settings.json

# Hooks
cat hooks.json | claudelint check-all --stdin --stdin-filename .claude/hooks.json

Incremental Linting

Slow on large projects

Symptom: claudelint check-all takes a long time because it checks every file.

Solution:

Use VCS-aware flags to check only changed files:

# Check only uncommitted changes
claudelint check-all --changed

# Check only files changed since a branch
claudelint check-all --since main

# Check only files changed since a tag
claudelint check-all --since v0.1.0

These flags require a git repository. If you're not in a git repo, you'll see a helpful error message.

Getting More Help

If you can't find a solution here:

1. Search existing issues: GitHub Issues

2. Check documentation:

   • Getting Started
   • Configuration
   • CLI Reference

3. Enable verbose output:

   claudelint check-all --verbose

4. Open a new issue with:

   • Command you ran
   • Error message
   • OS and Node version (node --version)
   • Output of claudelint check-all --verbose

Quick Reference

Common commands

# Initialize config
claudelint init

# Run all validation
claudelint check-all

# List all rules
claudelint list-rules

# Auto-fix issues
claudelint check-all --fix

# Check config
claudelint print-config

# Clear cache
claudelint cache-clear

# Get help
claudelint --help

Common config patterns

{
  "rules": {
    "skill-missing-version": "off",
    "claude-md-size": "warn",
    "skill-dangerous-command": "error"
  },
  "extends": [],
  "ignorePatterns": ["node_modules/", "dist/"]
}

See Configuration Guide for complete reference.