Common issues and solutions when using YARD-Lint.

• Installation Issues
• Configuration Errors
• Git and Diff Mode Issues
• Performance Problems
• False Positives
• CI/CD Issues
• Common Error Messages
• FAQ

Problem: Running yard-lint shows "command not found".

Cause: Gem executable not in $PATH.

Solutions:

1. Use bundle exec:

bundle exec yard-lint lib/

2. Install binstubs:

bundle binstubs yard-lint
./bin/yard-lint lib/

3. Add bundler bin to PATH:

export PATH="./bin:$PATH"
yard-lint lib/

Problem: Ruby can't find the YARD-Lint gem.

Cause: Gem not installed in current Ruby environment.

Solutions:

1. Install gem:

bundle install

2. Check which Ruby you're using:

which ruby
ruby --version
rbenv versions  # or rvm list

3. Install for correct Ruby:

gem install yard-lint

Problem: Bundler reports conflicting gem versions.

Cause: YARD-Lint dependencies conflict with other gems.

Solutions:

1. Update bundle:

bundle update yard-lint

2. Check dependency constraints in Gemfile:

gem 'yard-lint', '~> 1.0'  # Allow patch updates

3. Use dependency resolution:

bundle update --conservative yard-lint

Problem: Configuration references validator that doesn't exist.

Error Example:

Error: Unknown validator: 'UndocumentedMethod'
  Did you mean: Documentation/UndocumentedObjects?

Cause: Typo in validator name or missing category prefix.

Solutions:

1. Check validator name spelling:

# Wrong:
UndocumentedMethod:
  Enabled: true

# Right:
Documentation/UndocumentedObjects:
  Enabled: true

2. See the Validators reference for the complete list of validator names (the same link YARD-Lint prints in the error message).

Problem: Invalid severity level in configuration.

Error Example:

Error: Invalid Severity for Documentation/UndocumentedObjects: 'erro'
  Valid values: error, warning, convention, never
  Did you mean: error?

Cause: Typo in severity level.

Solutions:

Valid severity values:

Documentation/UndocumentedObjects:
  Severity: error       # ✓
  Severity: warning     # ✓
  Severity: convention  # ✓
  Severity: never       # ✓
  Severity: erro        # ✗ Invalid

Problem: Using string instead of boolean for Enabled.

Error Example:

Error: Invalid Enabled value: 'yes'
  Must be true or false

Cause: YAML requires boolean values, not strings.

Solutions:

# Wrong:
Documentation/UndocumentedObjects:
  Enabled: yes   # ✗
  Enabled: "true" # ✗

# Right:
Documentation/UndocumentedObjects:
  Enabled: true  # ✓
  Enabled: false # ✓

Problem: YARD-Lint can't find .yard-lint.yml.

Cause: Config file not in expected location.

Solutions:

1. Check current directory:

ls -la .yard-lint.yml

2. Specify config path:

yard-lint lib/ --config config/yard-lint.yml

3. Generate new config:

yard-lint --init

Problem: Configuration file has YAML syntax errors.

Error Example:

Error: Invalid YAML in .yard-lint.yml
  mapping values are not allowed in this context

Cause: YAML formatting errors.

Solutions:

1. Validate YAML syntax online: yamllint.com

2. Common YAML mistakes:

# Wrong: Missing space after colon
Documentation/UndocumentedObjects:
  Enabled:true

# Right: Space after colon
Documentation/UndocumentedObjects:
  Enabled: true

# Wrong: Inconsistent indentation
AllValidators:
 Exclude:
    - 'vendor/**/*'

# Right: Consistent 2-space indentation
AllValidators:
  Exclude:
    - 'vendor/**/*'

Problem: Git ref doesn't exist.

Error Example:

yard-lint lib/ --diff main
fatal: bad revision 'main'

Cause: Branch main doesn't exist locally.

Solutions:

1. Fetch the branch:

git fetch origin main
yard-lint lib/ --diff origin/main

2. Use existing branch:

git branch -a  # List all branches
yard-lint lib/ --diff master  # or develop, etc.

3. Let YARD-Lint auto-detect:

yard-lint lib/ --diff  # Auto-detects main/master

Problem: Diff mode finds no files.

Cause: No Ruby files changed since specified ref.

Solutions:

This is normal if you haven't changed any .rb files. To verify:

# Check what files changed
git diff --name-only main

# Check Ruby files specifically
git diff --name-only main | grep '\.rb$'

Problem: CI fails with "unknown revision 'origin/main...HEAD'".

Error in CI:

fatal: bad revision 'origin/main...HEAD'

Cause: Shallow clone missing git history.

Solutions:

Add fetch-depth: 0 to checkout action:

# Wrong:
- uses: actions/checkout@v4

# Right:
- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Get full history for --diff

Problem: --diff tries to lint files that were deleted.

Behavior: YARD-Lint automatically skips files that don't exist.

No action needed: This is handled automatically.

Problem: YARD-Lint is slow on large projects (10,000+ files).

Solutions:

1. Use diff mode to check only changed files:

yard-lint lib/ --diff main  # Much faster

2. Exclude unnecessary directories:

# .yard-lint.yml
AllValidators:
  Exclude:
    - 'vendor/**/*'
    - 'node_modules/**/*'
    - 'spec/**/*'
    - 'test/**/*'

3. Disable expensive validators:

# Disable opt-in validators
Tags/ExampleStyle:
  Enabled: false  # RuboCop on examples is slow

Tags/TagGroupSeparator:
  Enabled: false

4. Use --only for specific checks:

# Only run fast validators
yard-lint lib/ --only Tags/TypeSyntax,Tags/Order

5. Disable progress indicator:

yard-lint lib/ --no-progress

Problem: YARD-Lint uses too much memory.

Cause: YARD parser keeps ASTs in memory.

Solutions:

1. Process directories separately:

yard-lint lib/models/
yard-lint lib/services/
yard-lint lib/controllers/

2. Use diff mode:

yard-lint lib/ --diff main

3. Increase system memory or use swap.

Problem: Tags/ExampleStyle validator takes too long.

Cause: Running RuboCop on every example is expensive.

Solutions:

1. Disable for most files:

Tags/ExampleStyle:
  Enabled: true
  Exclude:
    - 'lib/internal/**/*'
    - 'spec/**/*'

2. Only enable for public API:

Tags/ExampleStyle:
  Enabled: false  # Disabled by default

# Then enable selectively
# @example (style checked)

3. Use faster linter:

Tags/ExampleStyle:
  Linter: standard  # Often faster than rubocop

Problem: YARD-Lint reports unknown tag that's valid.

Cause: Tag might be from YARD plugin or custom tag.

Solutions:

1. Check if tag is actually valid:

   • See YARD tag list

2. Disable validator for that file:

Warnings/UnknownTag:
  Exclude:
    - 'lib/file_with_custom_tags.rb'

3. If it's a common false positive, report issue on GitHub.

Problem: YARD-Lint reports type as invalid but class exists.

Cause: Class not loaded in YARD-Lint's runtime.

Solutions:

1. Add to ExtraTypes:

Tags/InvalidTypes:
  ExtraTypes:
    - MyCustomClass
    - Company::NamespacedClass

2. Check class name spelling:

# Make sure class name matches exactly
# @param user [MyClass] not [myClass] or [Myclass]

Problem: After enabling Tags/InvalidTypes: StrictConstantNames: true (or using the strict template), a type that is real — but defined only in an un-analyzed gem — is reported.

Cause: StrictConstantNames flags CamelCase types that are neither loaded Ruby constants nor defined in your analyzed codebase. Types living only in dependencies you don't analyze can't be resolved.

Solutions:

1. Add the type(s) to ExtraTypes:

Tags/InvalidTypes:
  StrictConstantNames: true
  ExtraTypes:
    - Faraday::Response
    - Dry::Monads::Result

2. Or leave StrictConstantNames: false (the default) if your project documents many dependency types.

Problem: Method in ExcludedMethods but still shows violations.

Cause: Pattern doesn't match method signature.

Solutions:

1. Check arity notation:

# Excludes initialize with ANY parameters:
ExcludedMethods:
  - 'initialize'

# Excludes ONLY parameter-less initialize:
ExcludedMethods:
  - 'initialize/0'

# Excludes initialize with exactly 2 parameters:
ExcludedMethods:
  - 'initialize/2'

2. Use regex for flexible matching:

ExcludedMethods:
  - '/^_/'       # All methods starting with _
  - '/^test_/'   # All test methods

Problem: YARD-Lint passes locally but fails in CI.

Causes & Solutions:

1. Different Ruby versions:

# Lock Ruby version in CI
ruby-version: '3.2.0'  # Not '3.2' or 'latest'

2. Different gem versions:

# Use Gemfile.lock
- run: bundle install --frozen

3. Different config files:

# Check which config is used
yard-lint lib/ --config .yard-lint.yml

4. Git history differences:

# Ensure full history for --diff
- uses: actions/checkout@v4
  with:
    fetch-depth: 0

Problem: CI job times out running YARD-Lint.

Solutions:

1. Use diff mode:

yard-lint lib/ --diff origin/main

2. Exclude large directories:

AllValidators:
  Exclude:
    - 'vendor/**/*'

3. Increase timeout:

# GitHub Actions
timeout-minutes: 30

Problem: Different results on different runs.

Cause: Non-deterministic validator behavior (rare).

Solutions:

1. Report issue with reproduction steps.

2. Pin YARD-Lint version:

gem 'yard-lint', '1.2.3'  # Not '~> 1.2'

Meaning: Method parameter not documented.

Solution:

# Add @param tag
# @param parameter_name [Type] description

Meaning: @param tag references non-existent parameter.

Solution:

# Check parameter name spelling
def method(correct_name)
  # Not usr_name, user_name, etc.
end

Meaning: YARD tags don't match EnforcedOrder.

Solution:

# Reorder tags to match config
# Typical order: @param, @option, @return, @raise, @example

Meaning: Malformed YARD type syntax.

Solutions:

# Fix common errors:
# @param items [Array<String>] not [Array<String]
# @param data [Hash{Symbol => String}] not [Hash<Symbol, String>]
# @return [String, Integer] not [String, Integer,]

A: Add file to global exclusions:

AllValidators:
  Exclude:
    - 'lib/legacy/old_file.rb'

A: No, exclusions are file-based. You can:

1. Exclude the method from the validator:

Documentation/UndocumentedObjects:
  ExcludedMethods:
    - 'specific_method_name'

2. Or disable the validator for the whole file.

A: YARD-Lint is stricter than YARD. YARD generates documentation with warnings; YARD-Lint enforces quality standards.

A: The Warnings/SyntaxError validator (enabled by default, severity error) reports Ruby files YARD cannot parse, instead of silently skipping them as earlier versions did. Fix the syntax error in the reported file. If you genuinely need the old skip-it-quietly behaviour, disable the validator:

Warnings/SyntaxError:
  Enabled: false

A: It no longer does — --changed includes untracked, non-ignored files, so a .rb file you just created is linted before you git add it. (Ignored files, e.g. those matched by .gitignore, are still skipped.)

A: Add value to descriptions:

# Bad: Just repeats the name
# @param user [User] The user

# Good: Explains purpose
# @param user [User] The user to authenticate

A: Not yet. Auto-fixing is planned for future versions. Track progress: GitHub Issue #XX.

A: Partially. Standard YARD plugins work, but custom tags may be reported as unknown. Add them to exclusions or ExtraTypes.

A: Open an issue on GitHub.

A: No, only Ruby. YARD is a Ruby documentation tool.

A: No, YARD-Lint only works with YARD documentation format.

A: Add to global exclusions:

AllValidators:
  Exclude:
    - 'spec/**/*'
    - 'test/**/*'

A: Possible causes:

1. No documentable objects in checked files
2. All objects excluded by configuration
3. YARD parsing errors (check for syntax errors)

Run with --stats to see breakdown.

If you can't find a solution here:

1. Check documentation:

   • Configuration
   • Validators
   • Advanced Usage

2. Search existing issues:

   • GitHub Issues

3. Ask for help:

   • Open a new issue with:
     • YARD-Lint version (yard-lint --version)
     • Ruby version (ruby --version)
     • Configuration file (.yard-lint.yml)
     • Example code that triggers the issue
     • Full error message

4. Contributing:

   • Found a bug? Open an issue
   • Want a feature? Open a feature request
   • Want to contribute? See CONTRIBUTING.md

• Configuration - Configuration reference
• Validators - Validator documentation
• Installation - Installation troubleshooting
• CI/CD Integration - CI-specific issues