Skip to main content

Troubleshoot common problems

Conan cannot find brpc​

brpc is not on Conan Center. You need to export the local recipe first:

conan export contrib/brpc/

Then re-run conan install.

First conan install is slow​

The first run builds brpc and protobuf from source, which takes several minutes. Subsequent runs use the Conan cache and are fast. If you need to force a rebuild:

conan install . --output-folder=build --build=missing

Homebrew protobuf conflicts (macOS)​

On macOS, Homebrew's system-wide protobuf (/opt/homebrew/include/google/protobuf/) can interfere with the Conan-provided version. Symptoms include protobuf version mismatch errors or abseil-related compile failures.

The brpc Conan recipe (contrib/brpc/conanfile.py) contains extensive workarounds for this -- it sets CMAKE_IGNORE_PATH and uses include-directory ordering to ensure Conan packages take precedence. If you still see Homebrew contamination:

  • Check that your Conan profile does not reference /opt/homebrew paths
  • Try conan remove '*' && conan install . --output-folder=build --build=missing for a clean rebuild

CMake preset not found​

If cmake --preset conan-release fails with "no such preset," run conan install first. The presets are generated by Conan into the build/ directory:

conan install . --output-folder=build --build=missing
cmake --preset conan-release

Tests crash with SEGFAULT​

Three tests (test_node, test_cli, test_leader_lease) crash deterministically due to upstream braft bugs in configuration-change and leader-failover code paths. These are labeled known_crash and excluded from the default test run:

ctest --preset conan-release --output-on-failure -LE known_crash

See UPSTREAM_BUGS.md for details.

Test failures from stale state​

Some tests write to relative ./data directories and use hardcoded ports. If a previous test run crashed and left state behind, later tests can fail with rename errors or port conflicts. The build system isolates each test into its own working directory under testwd/, but if you see flaky failures:

rm -rf build/build/Release/test/testwd/
cmake --build --preset conan-release
ctest --preset conan-release --output-on-failure -LE known_crash
npm run build

Read the error output -- it tells you exactly which file has a bad link and what path it tried to resolve.

docusaurus: command not found​

The Docusaurus binary comes from the project's npm dependencies. Install them first:

npm ci

GitHub Pages shows a 404​

The production docs are served at /docs/, not at the site root. The root page (/) redirects to /docs/. If you see a 404 at the root, the redirect page (src/pages/index.js) may not have been deployed.