Troubleshooting

Common issues and solutions.

Build Issues

"toolchain not found"

Install the nightly toolchain:

rustup toolchain install nightly

Linux Audio Errors

Install ALSA development packages:

sudo apt install alsa libasound2-dev

Slow Compilation

Use release mode for faster runtime:

cargo build --release

Runtime Issues

No Audio Output

Check audio device is available
Verify sample rate matches system
Ensure output block is connected

Crackling/Glitches

Increase buffer size
Check CPU usage
Avoid allocations in audio thread
Profile for bottlenecks

Silence

Verify block connections
Check gain levels (not -inf dB)
Ensure prepare() was called

FFI Issues

"Cannot find -ldsp"

Ensure Rust crate builds successfully
Check Corrosion configuration
Verify staticlib crate type

Header Not Found

Verify target_include_directories in CMake:

target_include_directories(${TARGET} PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/dsp/include)

Linking Errors

Check crate type in Cargo.toml:

[lib]
crate-type = ["staticlib"]

Parameter Issues

Parameters Not Updating

Verify parameter indices match
Check apply_parameters() implementation
Ensure JUCE is calling Process() with params

Wrong Parameter Values

Verify JSON/code generation sync
Check parameter count matches
Debug print received values

Getting Help

Check GitHub Issues
Search existing discussions
Open a new issue with:
- bbx_audio version
- Platform and OS
- Minimal reproduction
- Error messages