afv-library/skills/configuring-code-analyzer/references/troubleshooting.md

Troubleshooting Code Analyzer Setup

Common issues and solutions during installation and configuration.

Installation Issues

sf CLI Not Found

Symptom: sf: command not found or 'sf' is not recognized

Solutions:

1. Check if installed: which sf or where sf
2. If not installed: npm install -g @salesforce/cli
3. If installed but not in PATH:
   • macOS/Linux: Add export PATH="$(npm prefix -g)/bin:$PATH" to ~/.zshrc or ~/.bashrc
   • Windows: Add npm global bin to System PATH
4. Restart terminal after PATH changes

Plugin Install Fails

Symptom: Error: EACCES permission denied or timeout errors

Solutions:

Error	Fix
Permission denied	sudo sf plugins install @salesforce/plugin-code-analyzer or fix npm permissions
Network timeout	Check proxy: npm config set proxy http://proxy:port
Node version error	Upgrade Node.js to 18+: nvm install 20 && nvm use 20
Corrupt install	sf plugins uninstall @salesforce/plugin-code-analyzer && sf plugins install @salesforce/plugin-code-analyzer

Plugin Version Mismatch

Symptom: Command flags don't work, unexpected behavior

Check version:

sf plugins --core | grep code-analyzer

Expected: @salesforce/plugin-code-analyzer v5.x+

If on v3/v4 (legacy):

sf plugins uninstall @salesforce/sfdx-scanner  # Remove legacy v3
sf plugins install @salesforce/plugin-code-analyzer  # Install v5+

Java Issues

Java Not Found

Symptom: PMD/CPD/SFGE fails with java: command not found or JAVA_HOME not set

Fix:

# macOS
brew install openjdk@11
export JAVA_HOME="/opt/homebrew/opt/openjdk@11"
export PATH="$JAVA_HOME/bin:$PATH"

# Add to ~/.zshrc for persistence
echo 'export JAVA_HOME="/opt/homebrew/opt/openjdk@11"' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc

Wrong Java Version

Symptom: UnsupportedClassVersionError or class file version X.Y

Fix: Code Analyzer needs Java 11+. Check and switch:

java -version  # Check current

# If using SDKMAN:
sdk install java 11.0.21-tem
sdk use java 11.0.21-tem

# If using Homebrew:
brew install openjdk@11
export JAVA_HOME="/opt/homebrew/opt/openjdk@11"

SFGE Out of Memory

Symptom: java.lang.OutOfMemoryError: Java heap space

Fix: Increase heap in code-analyzer.yml:

engines:
  sfge:
    java_max_heap_size: "4g"  # Default is 1g, increase for large projects

Guidelines:

Project Size	Heap Recommendation
< 200 Apex classes	2g
200-500 Apex classes	4g
500-1000 Apex classes	6g
1000+ Apex classes	8g

Node.js Issues

Node.js Version Too Old

Symptom: Error: Node.js v16 is not supported or ESLint failures

Fix:

# Check version
node --version

# Upgrade via nvm
nvm install 20
nvm use 20
nvm alias default 20

# Or via Homebrew
brew upgrade node

ESLint Config Conflicts

Symptom: ESLint rules not loading, or unexpected rules appearing

Possible causes:

1. Project has its own .eslintrc.* conflicting with Code Analyzer's built-in config
2. auto_discover_eslint_config is enabled but project config is incompatible

Fix options:

# Option A: Disable auto-discovery (use only Code Analyzer's built-in rules)
engines:
  eslint:
    auto_discover_eslint_config: false

# Option B: Use project's config exclusively
engines:
  eslint:
    auto_discover_eslint_config: true
    disable_javascript_base_config: true
    disable_typescript_base_config: true
    disable_lwc_base_config: true

Configuration Issues

Config File Not Picked Up

Symptom: Custom settings not applied, default behavior persists

Checklist:

1. File must be named exactly code-analyzer.yml or code-analyzer.yaml
2. File must be in the current working directory when running commands
3. Or specify explicitly: --config-file ./path/to/code-analyzer.yml
4. Check for YAML syntax errors: sf code-analyzer config --config-file code-analyzer.yml

YAML Syntax Errors

Symptom: YAMLException: bad indentation or unexpected token

Common YAML mistakes:

# WRONG - tabs instead of spaces
engines:
	pmd:           # TAB character - YAML requires spaces!

# CORRECT - spaces only
engines:
  pmd:             # 2 spaces

# WRONG - missing quotes around special values
rules:
  pmd:
    MyRule:
      severity: High    # String values need quotes or use numbers

# CORRECT
rules:
  pmd:
    MyRule:
      severity: 2       # Use numbers 1-5
      # OR
      severity: "High"  # Or quoted strings

Unknown Engine or Rule Name

Symptom: Rule selector returns 0 results

Fix: Verify the engine/rule name:

# List all available engines
sf code-analyzer rules --rule-selector all 2>&1 | head -50

# Search for a specific rule
sf code-analyzer rules --rule-selector all 2>&1 | grep -i "CRUD"

# List rules for specific engine
sf code-analyzer rules --rule-selector pmd 2>&1 | head -50

Engine-Specific Issues

PMD: Custom Rules Not Loading

Symptom: Custom PMD rules don't appear in sf code-analyzer rules

Checklist:

1. Ruleset XML must be valid PMD format
2. Path in custom_rulesets must be relative to config_root
3. For Java rules: JAR must be in java_classpath_entries
4. Validate: sf code-analyzer rules --rule-selector pmd:<YourRuleName>

RetireJS: False Positives on Test Files

Symptom: RetireJS flags test fixtures or mock data

Fix: Add test paths to ignores:

ignores:
  files:
    - "**/test/**"
    - "**/__tests__/**"
    - "**/jest-mocks/**"
    - "**/*.test.js"
    - "**/*.spec.js"

Flow Engine: Python Not Found

Symptom: python3: command not found when scanning Flows

Fix:

# Install Python 3
brew install python3  # macOS
# OR
sudo apt install python3  # Linux

# If python3 is at non-standard path:
# code-analyzer.yml
engines:
  flow:
    python_command: "/usr/local/bin/python3"

ApexGuru: Authentication Error

Symptom: No authenticated org found or Session expired

Fix:

# Login to org
sf org login web --alias my-org

# Set as default
sf config set target-org my-org

# Configure in code-analyzer.yml
engines:
  apexguru:
    target_org: "my-org"

Performance Issues

Scan Takes Too Long

Possible causes and solutions:

Cause	Solution
SFGE on large project	Increase heap, reduce thread timeout, or disable SFGE for routine scans
Scanning node_modules	Add **/node_modules/** to ignores
Too many engines enabled	Use --rule-selector Recommended instead of all for routine scans
Large static resources	Add **/staticresources/** to ignores
Many Flow files	Flow engine can be slow; scan Flows separately

Reduce Scan Time in CI

# Fast CI scan: recommended rules only, severity gate at High
sf code-analyzer run \
  --rule-selector Recommended \
  --severity-threshold 2 \
  --target force-app/main/default \
  --output-file results.json

Getting Help

If none of the above solves your issue:

1. Check logs: Look in the log folder (default: /tmp or configured log_folder)
2. Increase log level: Set log_level: 5 in config for maximum detail
3. Run with debug: SF_LOG_LEVEL=debug sf code-analyzer run ...
4. File an issue: https://github.com/forcedotcom/code-analyzer-core/issues