Troubleshooting

Troubleshooting

Build Issues

LLVM not found

CMake Error: Could not find a package configuration file provided by "LLVM"

Set the paths manually:

LLVM_DIR=/usr/lib/llvm-20/lib/cmake/llvm \
Clang_DIR=/usr/lib/llvm-20/lib/cmake/clang \
./build.sh

On macOS with Homebrew:

LLVM_DIR=$(brew --prefix llvm)/lib/cmake/llvm \
Clang_DIR=$(brew --prefix llvm)/lib/cmake/clang \
./build.sh

LLVM version too old

The analyzer requires LLVM 19+. Check your version:

llvm-config --version

Linking errors with LLVM

The default configuration uses LLVM_LINK_LLVM_DYLIB=ON (dynamic linking). If your LLVM installation doesn't provide libLLVM.so/libLLVM.dylib, try:

cmake -S . -B build -DLLVM_LINK_LLVM_DYLIB=OFF ...

---

Analysis Issues

"No analyzable functions" on every file

• Check that include paths are correct (-I)
• Verify the compile database entries point to existing files
• Use --timing to see if compilation fails silently
• Try --dump-ir=debug/ to inspect the generated IR

Cross-platform compile database mismatch

A compile_commands.json generated on macOS often fails in Linux CI:

fatal error: 'TargetConditionals.h' file not found

Solutions:

• Generate the compile database on the same platform as the analyzer
• Use --compdb-fast to strip platform-specific flags
• Extend the Docker image with needed headers

Analysis is too slow

• Switch to --analysis-profile=fast
• Use --jobs=<N> for parallel processing
• Use --exclude-dir to skip third-party code
• Use --compdb-fast to speed up compilation from compile databases
• Use --resource-summary-cache-memory-only to avoid filesystem I/O

Too many false positives

• Use --warnings-only to focus on important findings
• Use --escape-model to suppress false stack escape warnings
• Use --only-dir or --only-file to focus on your code
• Exclude third-party code with --exclude-dir=_deps,vendor,third_party

Resource lifetime false positives

• Check that your --resource-model has correct acquire/release pairings
• Verify arg indices match the actual function signatures
• Use ResourceLifetime.IncompleteInterproc warnings to identify missing model entries
• Enable cross-TU summaries for better precision with multi-file projects

---

Docker Issues

Stale compile_commands.json paths

If the compile database was generated in a different checkout root (e.g., /tmp/ci-build/...) while the repo is mounted at /workspace, the Docker entrypoint automatically creates a compatibility symlink when safe.

Permission errors in Docker

Run with matching user/group:

docker run --rm \
  -u "$(id -u):$(id -g)" \
  -v "$PWD:/workspace" \
  coretrace-stack-analyzer

---

CI Issues

"Analyzer binary not found"

The CI adapter looks for the binary at build/stack_usage_analyzer by default. Override with:

python3 scripts/ci/run_code_analysis.py --analyzer /path/to/stack_usage_analyzer ...

"No input files selected"

Check that:

• compile_commands.json exists and is valid JSON
• Source files referenced in the database actually exist
• --exclude patterns are not too broad
• Enable --inputs-from-git as a fallback

SARIF upload fails

Ensure the workflow has the correct permissions:

permissions:
  contents: read
  security-events: write

---

Debugging Tips

Dump generated LLVM IR

./build/stack_usage_analyzer main.cpp --dump-ir=debug/main.ll

Inspect the IR to understand what the analyzer sees.

Trace filter decisions

./build/stack_usage_analyzer --compdb=build --only-dir=src/ --dump-filter 2>filter.log

Enable timing

./build/stack_usage_analyzer --compdb=build --timing 2>timing.log

Shows per-file compilation and analysis times, plus cross-TU summary iteration times.

Verbose logging

The analyzer uses coretrace-logger. Debug-level logging is available but not exposed via CLI flags by default. Look for status lines on stderr for inter-procedural analysis status.