buck2-build-troubleshoot

name	buck2-build-troubleshoot
description	Debugs Buck2 build failures systematically by analyzing error logs, checking common issues (cache, visibility, cycles), and suggesting fixes. Use when builds fail, tests won't run, or Buck2 reports errors.

Buck2 Build Troubleshoot

Overview

This skill provides systematic debugging for Buck2 build failures. It analyzes error logs, identifies common issues, and suggests concrete fixes. Instead of manually parsing verbose build output, use the build doctor script to diagnose problems quickly.

Use this skill when:

• Buck2 build fails with cryptic errors
• Targets won't compile or link
• Tests fail to run
• Visibility errors prevent building
• Dependency cycles are suspected
• Cache issues cause inconsistent builds
• Remote execution fails

This skill provides:

• scripts/build_doctor.py - Automated build diagnostics
• references/common_errors.md - Error patterns and solutions
• Systematic debugging workflow
• Quick fixes for common issues

Quick Start

When a build fails:

# Run the build doctor
python3 scripts/build_doctor.py

# Or analyze specific target
python3 scripts/build_doctor.py //src/tools:mytool

# Verbose analysis
python3 scripts/build_doctor.py --verbose //src/tools:mytool

The script will:

1. Check what failed recently
2. Analyze error messages
3. Check common issues (cache, visibility, cycles)
4. Suggest specific fixes

Common Build Failures

Compilation Errors

Rust compilation failure:

Error: rustc failed with exit code 1

Diagnosis:

# See full error
python3 scripts/build_doctor.py --show-logs //target

# Check source files
buck2 query "//target" --output-attribute srcs

# Verify dependencies
buck2 query "deps('//target', 1)"

Common fixes:

• Fix syntax errors in source code
• Add missing dependencies to BUILD file
• Check Rust edition compatibility
• Verify feature flags

Dependency Errors

Missing dependency:

Error: unresolved import `foo::bar`

Fix:

# Add to BUILD file deps:
deps = [
    "//path/to:foo",
    "third-party//crate:crate",
]

Circular dependency:

Error: cycle detected in dependency graph

Diagnosis:

# Find the cycle
python3 scripts/build_doctor.py --check-cycles //src/...

# Investigate specific path
buck2 query "allpaths('//target/a', '//target/b')"
buck2 query "allpaths('//target/b', '//target/a')"

Fix: Break the cycle by:

• Extracting shared code to new library
• Removing unnecessary dependency
• Using dependency injection instead of direct import

Visibility Errors

Cannot access target:

Error: //src/app:app cannot depend on //src/lib:internal (not visible)

Diagnosis:

# Check visibility settings
buck2 query "//src/lib:internal" --output-attribute visibility

# See who can access it
python3 scripts/build_doctor.py --check-visibility //src/lib:internal

Fix:

# In BUILD file, update visibility:
depot.rust_library(
    name = "internal",
    visibility = [
        "//src/app/...",  # Allow src/app access
        # or
        "PUBLIC",  # Allow everyone
    ],
)

Linking Errors

Undefined reference:

Error: undefined reference to `symbol`

Common causes:

• Missing library dependency
• Wrong link order
• ABI mismatch between libraries

Fix:

# Check all dependencies are present
buck2 query "deps('//target', 1)" --output-attribute deps

# For C++, check link order in BUILD

Test Failures

Tests won't run:

Error: No tests found

Diagnosis:

# Verify test target exists
buck2 targets //path:test

# Check test is properly defined
buck2 query "//path:test" --output-attribute buck.type

Fix:

# Ensure BUILD has test target:
depot.rust_test(
    name = "test",
    srcs = glob(["src/**/*.rs"]),
)

Systematic Debugging Workflow

Step 1: Identify What Failed

# Recent failures
buck2 log what-failed

# Or use build doctor
python3 scripts/build_doctor.py

Step 2: Read the Error

# Full error output
buck2 log last

# Specific target
buck2 build //target -v 2  # Verbose mode

Step 3: Check Common Issues

# Run automated checks
python3 scripts/build_doctor.py --all-checks //target

This checks:

• Cache corruption
• Visibility issues
• Circular dependencies
• Missing dependencies
• Common configuration errors

Step 4: Verify Target Configuration

# Inspect BUILD file
buck2 query "//target" --json | jq

# Check dependencies
buck2 query "deps('//target', 1)"

# Verify source files exist
buck2 query "//target" --output-attribute srcs

Step 5: Test in Isolation

# Build single target
buck2 build //target

# Build with fresh cache
buck2 clean && buck2 build //target

# Skip cache
buck2 build //target --no-remote-cache

Build Doctor Script Usage

Basic Diagnostics

# Analyze last failure
python3 scripts/build_doctor.py

# Specific target
python3 scripts/build_doctor.py //src/tools:mytool

# Multiple targets
python3 scripts/build_doctor.py //src/tools:tool1 //src/lib:lib2

Check Options

# Check cache issues
python3 scripts/build_doctor.py --check-cache

# Check visibility
python3 scripts/build_doctor.py --check-visibility //target

# Check for cycles
python3 scripts/build_doctor.py --check-cycles //src/...

# Run all checks
python3 scripts/build_doctor.py --all-checks //target

Output Options

# Verbose output
python3 scripts/build_doctor.py --verbose //target

# Show build logs
python3 scripts/build_doctor.py --show-logs //target

# JSON output for scripting
python3 scripts/build_doctor.py --json //target

Common Error Patterns

Pattern: "No such target"

Error:

Error: No targets found matching //src/tools:missing

Causes:

• Typo in target name
• Target not defined in BUILD
• Wrong package path

Fix:

# List available targets
buck2 targets //src/tools:

# Check BUILD file exists
ls -la src/tools/BUILD

# Search for target
buck2 targets //... | grep missing

Pattern: "Glob matched no files"

Error:

Warning: glob(["src/**/*.rs"]) matched no files

Causes:

• Wrong glob pattern
• Files in wrong location
• Missing source directory

Fix:

# Check directory structure
ls -la src/

# Verify glob pattern
# For Rust binary: src/main.rs
# For Rust library: src/lib.rs

Pattern: "Cannot find module"

Error (Rust):

Error: cannot find module `foo` in crate root

Fix:

1. Add module declaration: mod foo; in lib.rs/main.rs
2. Or add file to same directory
3. Or add as dependency in BUILD

Pattern: "Feature not enabled"

Error:

Error: feature `foo` is required

Fix:

# Add to BUILD file:
deps = [
    "third-party//crate:crate[foo]",  # Enable feature
]

Pattern: "Output already used"

Error:

Error: output directory already in use

Causes:

• Multiple builds running
• Stale lock files
• Buck daemon issues

Fix:

# Kill buck daemon
buck2 kill

# Clean and rebuild
buck2 clean
buck2 build //target

Advanced Troubleshooting

Cache Issues

Symptoms:

• Inconsistent builds
• Changes not reflected
• Stale outputs

Diagnosis:

# Disable cache and test
buck2 build --no-remote-cache //target

# Check cache configuration
buck2 audit config cache

Fix:

# Clear local cache
buck2 clean

# For persistent issues, check .buckconfig
cat .buckconfig | grep -A5 cache

Remote Execution Issues

Symptoms:

• Builds fail in CI but work locally
• Platform-specific errors
• Missing dependencies in remote environment

Diagnosis:

# Build locally only
buck2 build --no-remote-execution //target

# Check platform configuration
buck2 audit config re

Fix:

• Verify all dependencies are in BUILD
• Check platform compatibility
• Ensure no local-only paths

Incremental Build Issues

Symptoms:

• Buck rebuilds everything
• No caching benefits
• Slow builds

Diagnosis:

# Check what changed
buck2 explain //target

# Verify target determinism
buck2 build //target
buck2 build //target  # Should be cached

Fix:

• Ensure reproducible builds
• Avoid generated source in working copy
• Check for timestamp dependencies

Integration with Other Tools

With jj Version Control

# Find what changed
jj diff --stat | cut -f2 | while read file; do
  buck2 query "owner('$file')"
done | while read target; do
  python3 scripts/build_doctor.py $target
done

With CI/CD

# In CI pipeline
if ! buck2 build @targets; then
  python3 scripts/build_doctor.py --json > diagnosis.json
  cat diagnosis.json
  exit 1
fi

With Target Determination

# Diagnose failures in changed targets
TARGETS_FILE="$(mktemp "${TMPDIR:-/tmp}/tdutil-targets.XXXXXX")"
trap 'rm -f -- "$TARGETS_FILE"' EXIT
buck2 run root//buck/tools/tdutil:tdutil -- --output "$TARGETS_FILE" --universe depot//src/...
buck2 build "@$TARGETS_FILE" || {
  python3 scripts/build_doctor.py --show-logs
}

Quick Reference

Must-Know Commands

# What failed recently
buck2 log what-failed

# Show last build log
buck2 log last

# Build with verbose output
buck2 build //target -v 2

# Clean everything
buck2 clean

# Kill buck daemon
buck2 kill

# Explain why rebuilding
buck2 explain //target

Common Quick Fixes

# 1. Clean build
buck2 clean && buck2 build //target

# 2. Kill daemon and retry
buck2 kill && buck2 build //target

# 3. Skip cache
buck2 build --no-remote-cache //target

# 4. Verbose output
buck2 build //target -v 2 2>&1 | tee build.log

# 5. Ignore broken targets during testing
buck2 test //... --keep-going

Troubleshooting Checklist

When builds fail, check:

• Error message clearly read
• Target exists (buck2 targets //path:)
• BUILD file syntax valid
• Source files exist and in right location
• Dependencies declared in BUILD
• Visibility allows access
• No circular dependencies
• Cache not corrupted (try buck2 clean)
• Buck daemon healthy (try buck2 kill)
• Recent changes didn't break build

Tips and Best Practices

1. Read the full error - Often the actual error is near the top, not bottom
2. Build with -v 2 - Verbose mode shows what's actually running
3. Test incrementally - Fix one error at a time
4. Use clean builds - When in doubt, buck2 clean
5. Check recent changes - Use jj log to see what changed
6. Isolate the problem - Build specific targets, not everything
7. Use build doctor - Automated checks save time
8. Keep BUILD files simple - Complex BUILD files are hard to debug

Getting Help

If stuck after trying these steps:

1. Run build doctor with verbose output
2. Collect full error logs: buck2 build //target -v 2 2>&1 > error.log
3. Check target configuration: buck2 query //target --json
4. Search for similar errors in documentation
5. Ask for help with specific error message and context