Skip to content
Brane Logo Brane

Troubleshooting

Troubleshooting

Section titled “Troubleshooting”

Installation

Section titled “Installation”

”Command not found” after installing

Section titled “”Command not found” after installing”
Terminal window
ls -la /usr/local/bin/brane
sudo chmod +x /usr/local/bin/brane
brane version

GLIBC version error (Linux)

Section titled “GLIBC version error (Linux)”

Check your version: ldd --version. GLIBC 2.27+ is required. Upgrade your OS or build from source if needed.

Docker permission denied

Section titled “Docker permission denied”
Terminal window
sudo usermod -aG docker "$USER"
# Log out and back in, then:
docker run hello-world

Node Startup

Section titled “Node Startup”

brane-api keeps restarting

Section titled “brane-api keeps restarting”

ScyllaDB takes 1-2 minutes to initialize. The API restarts automatically until the database is ready.

Terminal window
docker ps          # Monitor status
docker logs brane-api  # Check logs

”No such image” when starting

Section titled “”No such image” when starting”

Re-download images or specify a custom path:

Terminal window
branectl download services central -f
branectl start --image-dir "./path/to/images" central

Port already in use

Section titled “Port already in use”
Terminal window
sudo lsof -i :50051

Stop the conflicting service or change the port in node.yml.

Packages

Section titled “Packages”

Build fails with Docker errors

Section titled “Build fails with Docker errors”
Terminal window
docker info             # Ensure Docker is running
docker buildx version   # Ensure BuildKit is available
docker buildx create --use  # Recreate builder if needed

Package test shows wrong output

Section titled “Package test shows wrong output”
  • Verify your script outputs valid YAML
  • Check output key names match the container.yml action output names
  • Verify the shebang line (#!/bin/bash or #!/usr/bin/env python3)

Push fails

Section titled “Push fails”
Terminal window
brane instance                               # Check login
brane login http://<INSTANCE> --username <NAME>  # Re-login
curl http://<INSTANCE>:50051/health              # Check reachability

Workflows

Section titled “Workflows”

”Package not found” in REPL

Section titled “”Package not found” in REPL”

The package hasn’t been pushed. Push it first:

Terminal window
brane package push <package_name>
brane package search   # Verify it's on the instance

Policy violation error

Section titled “Policy violation error”

The worker node’s policy is blocking the operation. Contact the domain’s policy expert to check and update the active policy.

Workflow hangs

Section titled “Workflow hangs”
  • Check all referenced worker nodes are running
  • Verify network connectivity between nodes
  • Check logs: docker logs brane-drv

Certificates

Section titled “Certificates”

”Certificate verification failed”

Section titled “”Certificate verification failed””
  • Ensure ca.pem in the central node matches the worker’s CA
  • Verify hostname in certificate matches actual hostname

”No client certificate found”

Section titled “”No client certificate found””
  • Client certificates must be at config/certs/<domain_id>/
  • Files must be named exactly ca.pem and client-id.pem

Getting Help

Section titled “Getting Help”
  1. Check container logs: docker logs <container_name>
  2. Search GitHub Issues
  3. Open a new issue with OS/Docker version, error message, steps to reproduce, and relevant logs