Reference

Troubleshooting

Symptom, cause, fix. Everything on this page is a failure that was actually produced on a real install, not a list of things that could theoretically go wrong.

Beacon will not connect

"Nothing answered at that address"

Beacon reached nothing at the host and port you gave it. Three causes, in order of how often they are the real one:

• You pointed at the wrong machine. The address is the machine running prometheus daemon, not the machine running Beacon. If they are different computers, localhost is wrong. This is the single most common first-setup failure.
• The daemon is not running. On that host: systemctl --user status prometheus.
• You cannot reach the host from here. Different network, tailnet down, firewall.

Settle it from the daemon's own machine first — curl localhost:8005/health there. If that answers, the daemon is fine and the problem is the address or the network. If it does not, stop looking at Beacon.

Chat loads but nothing streams

REST is working and the WebSocket is not. They authenticate by different mechanisms — a bearer header versus the first frame of the handshake — so one can fail alone. Beacon's Connection settings panel has a Test that checks each separately. Check that port 8010 is reachable as well as 8005.

It says connected but the token was rejected

Rotating the token on the daemon invalidates every client holding the old one. Paste the new token into each Beacon and each device. If you rotated and the daemon still rejects the new token, the daemon may be holding the old value from its environment — see below.

A rotated token did not take effect

A process that read the token from an environment variable at startup keeps that value for its entire life; the operating system offers no way to change a running process's environment. If the deployment passes the token as an environment variable rather than letting the daemon read the env file, a rotation needs a restart:

systemctl --user restart prometheus
curl -s localhost:8005/health

An empty reply from curl

curl -s suppresses the connection error, so a refused port and a genuinely empty response look identical — both print nothing and return you to the prompt. Drop the -s, or check the exit code, before concluding the endpoint answered with nothing. Silence is not a measurement.

doctor prints a wall of logging before its report

About twenty-five lines of tool-registration INFO print before the report starts. Nothing is wrong — doctor is not in the quiet-console list yet. Scroll to the line that reads oara doctor; the report starts there. The bwrap failure also prints twice, once as a raw log line and once correctly inside the report as !.

install-service exits 1 but seems to have worked

It did work. The command writes the unit file, then runs systemctl --user daemon-reload; with no user bus available — a container, an SSH session without a login session — the reload fails and the command exits 1 having already written the file. Check for ~/.config/systemd/user/prometheus.service, then run the reload yourself from a session that has a bus. See Run it always-on.

"Bash write floor: mode 'auto' but UNAVAILABLE"

doctor is telling you bubblewrap is not installed, so bash is running with no kernel write floor. This is a warning rather than an error because Prometheus runs fine without it — but it means one of the confinement layers you may think you have is not actually there. Either install it:

sudo apt install bubblewrap

…or set security.bash_write_confinement: off so you are running without it knowingly rather than by accident. Configuration has what each layer does and does not cover.

oara config prints its own help and does nothing

Expected, if surprising. oara config with no flags prints usage and exits 0. The flag you want is --show-defaults, which prints the shipped configuration template with every documented key and its comments. There is currently no command that shows the merged, loaded configuration — oara doctor tells you which file loaded, and reading that file tells you what is in it.

oara --version reports an old version

oara --version prints the version recorded in packaging metadata, which currently lags the tree. It is not a reliable indicator of what code you are running. To know that, check the commit in your checkout or reinstall from a known ref.

Setup found no inference server

oara setup probes four well-known local ports — llama.cpp on 8080, Ollama on 11434, LM Studio on 1234, vLLM on 8000 — and if none answers it refuses to write a config at all, exiting 2 with install instructions for Ollama and llama.cpp. That refusal is deliberate: a config that is known not to work is worse than no config. Start a server, or point setup somewhere else with --probe-url URL, or use a cloud provider with --provider NAME.

Still stuck

Run oara doctor and read it top to bottom. Fix the topmost ✗ and re-run rather than working down the list — the first error usually explains the ones below it. If that does not resolve it, open an issue with the full doctor output, with any host names or tokens removed.