Troubleshooting

This guide helps you diagnose and fix common issues with Bazelle.

Diagnostic Commands

Before troubleshooting, gather information:

# Check Bazelle version
bazelle version

# Run with verbose logging
bazelle -v 3 update

# Run with trace logging (very detailed)
bazelle -v 4 update

# Check what would change without applying
bazelle fix --dry-run

Common Issues

”No languages detected” during init

Symptom: bazelle init reports no languages found.

Causes:

• No source files in recognized locations
• Files use unexpected extensions

Solution:

1. Verify source files exist in your project
2. Check file extensions match expected patterns:
   • Go: .go
   • Kotlin: .kt, .kts
   • Python: .py
   • C/C++: .c, .cc, .cpp, .h, .hpp
3. Use --languages flag to specify manually:

   bazelle init --languages go,kotlin

Language not generating rules

Symptom: Running bazelle update doesn’t generate rules for your language.

Causes:

• Language not enabled
• Files not in expected directory structure
• Directory is excluded

Solution:

Kotlin

# 1. Enable Kotlin in root BUILD.bazel
# gazelle:kotlin_enabled true

Kotlin requires Maven-style layout:

src/main/kotlin/   → kt_jvm_library
src/test/kotlin/   → kt_jvm_test

Python

# 1. Enable Python in root BUILD.bazel
# gazelle:python_enabled true

Python works with any .py files in the directory.

BUILD file conflicts

Symptom: Error about conflicting rules or duplicate targets.

Causes:

• Multiple extensions trying to generate the same target
• Manual rules conflict with generated ones

Solution:

1. Use # gazelle:exclude to prevent generation in specific directories
2. Use # keep comment to preserve manual rules:

   # keep
   my_custom_library(
       name = "custom",
       ...
   )

3. Delete conflicting generated rules and re-run

Incremental mode not working

Symptom: --incremental flag doesn’t speed up updates.

Causes:

• No previous state exists
• State was invalidated
• Config changes detected

Solution:

# First run creates state
bazelle update

# Check state exists
ls -la .bazelle/

# If missing, run full update first
bazelle update --force

Note

Incremental state is stored in .bazelle/ directory. You can add this to .gitignore or commit it for team-wide incremental updates.

Watch mode stops responding

Symptom: bazelle watch stops detecting changes.

Causes:

• File system watcher limit reached
• Process backgrounded incorrectly

Solution:

macOS

macOS has generous file watcher limits. Try restarting the command.

Linux

Increase inotify limit:

# Temporary
sudo sysctl fs.inotify.max_user_watches=524288

# Permanent (add to /etc/sysctl.conf)
fs.inotify.max_user_watches=524288

Daemon not starting

Symptom: bazelle daemon start fails or daemon crashes immediately.

Causes:

• Stale PID/socket files from previous crash
• Socket directory doesn’t exist
• Permission issues

Solution:

1. Clean up stale files:

   rm -f ~/.bazelle/daemon.sock ~/.bazelle/daemon.pid

2. Run in foreground to see errors:

   bazelle daemon start --foreground

3. Check permissions on ~/.bazelle/ directory

Daemon connection refused

Symptom: VS Code or CLI can’t connect to running daemon.

Causes:

• Daemon crashed but PID file still exists
• Socket file permissions incorrect
• Wrong socket path configured

Solution:

1. Check daemon status:

   bazelle daemon status

2. If it shows “stale PID file”, clean up:

   bazelle daemon start  # Auto-cleans stale files

3. Verify socket permissions (should be 0600):

   ls -la ~/.bazelle/daemon.sock

4. Check VS Code is using correct socket path in settings

Daemon using too much memory

Symptom: Daemon process grows in memory over time.

Causes:

• Watching too many files
• Memory leak (rare)

Solution:

1. Restart the daemon periodically:

   bazelle daemon restart

2. Use .gitignore patterns to exclude unnecessary files
3. Watch only specific subdirectories:

   # In VS Code or via daemon API, specify paths
   bazelle watch ./src  # Instead of entire workspace

Wrong dependencies generated

Symptom: Generated deps attribute has incorrect targets.

Causes:

• Import statements not recognized
• External dependencies not configured
• Resolver can’t find matching target

Solution:

1. Check import statements are valid
2. For external deps, verify MODULE.bazel configuration
3. Use # gazelle:resolve directive to fix specific imports:

   # gazelle:resolve py my.package //third_party:my_package

4. Run with verbose logging to see resolution:

   bazelle -v 3 update

Pre-commit hooks failing

Symptom: bazelle update --check fails in CI/pre-commit.

Causes:

• BUILD files are out of sync with source
• Different Bazelle version in CI

Solution:

1. Run bazelle update locally and commit changes
2. Ensure CI uses the same Bazelle version
3. Consider adding to pre-commit:

   .pre-commit-config.yaml

   - repo: local
     hooks:
       - id: bazelle
         name: Update BUILD files
         entry: bazelle update
         language: system
         pass_filenames: false

Debug Logging

Enable detailed logging to diagnose issues:

# Verbosity levels
bazelle -v 0 update  # Errors only
bazelle -v 1 update  # Warnings (default)
bazelle -v 2 update  # Info
bazelle -v 3 update  # Debug
bazelle -v 4 update  # Trace

# JSON output for parsing
bazelle --log-format json update 2>debug.json

Getting Help

If you can’t resolve an issue:

1. Search existing issues
2. Create a new issue with:
   • Bazelle version (bazelle version)
   • Bazel version (bazel version)
   • Minimal reproduction steps
   • Debug logs (bazelle -v 3 update)