Troubleshooting

A symptom-first catalog for when Honeycomb does not behave. Find your symptom, read the likely cause, run the fix, and use the escalation step if it persists. Honeycomb is built to degrade quietly rather than crash, so the most common "problem" is that something is running in a reduced mode without telling you. The dashboard is your single best diagnostic: it names what is degraded in plain language instead of showing a green light that is not telling the truth.

Related:

#First, read the dashboard

Before working through a specific symptom, open the dashboard:

honeycomb dashboard

The dashboard's health strip names any subsystem that is down (storage, the meaning-search model, or a missing piece of the store). The recall bar shows a "lexical fallback" badge when the last recall ran by matching words rather than meaning. Most of the symptoms below can be confirmed at a glance here.

#Install failures

#The honeycomb command is not found

Symptom: The installer finished, but running honeycomb status reports "command not found."

Likely cause: Installing a global command does not refresh the current terminal's path. The freshly installed honeycomb exists, but this shell does not know about it yet.

Fix: Open a new terminal window and run honeycomb status again. A fresh shell picks up the new command. If it still is not found in a new window, your global-command location may not be on your path; reinstall with the one-command installer from Installation, which resolves the command by its full location during setup.

Escalation: If the command is still missing after reinstalling in a fresh terminal, see Frequently asked questions or reach out through the support link there.

#The installer stopped and printed a command to run

Symptom: The installer exited early with a message asking you to run a specific command yourself.

Likely cause: A step needed elevated permission it could not obtain (commonly installing Node on a locked-down machine). This is by design: the installer stops cleanly rather than leaving a half-finished state.

Fix: Run the exact command the installer printed, then paste the original install line again. The installer is safe to re-run; it picks up where it left off.

Escalation: If the printed command also fails, you likely need an administrator on that machine to grant install permission.

#The installer is slow or seems to hang on first run

Symptom: Install or the first session takes longer than expected.

Likely cause: The meaning-search model downloads its weights the first time it is needed, in the background. This is a one-time download and never blocks the installer or the dashboard.

Fix: Let it finish. Until the model is warm, recall still works by matching words. You can keep working; meaning-search switches on by itself once the download completes.

Escalation: None needed. If recall quality matters immediately and the model has not warmed up, see recall returns nothing for how to confirm which mode recall is in.

#The helper is not running

#The dashboard did not open

Symptom: The installer finished but no browser tab opened.

Likely cause: The opener could not launch your browser, which is non-fatal by design. The local address is printed for you to open by hand.

Fix: Copy the local dashboard address from the installer output and open it in your browser, or run:

honeycomb dashboard

Escalation: If the page does not load at the local address, the helper may not be running. See the next entry.

#The helper (daemon) is not reachable

Symptom: honeycomb status reports the helper as down, or dashboard pages do not load.

Likely cause: The small background helper that does all the real work is not running, or did not come up within its start window.

Fix: Run a command that brings it up. honeycomb status itself probes the helper and starts it if it is absent; running it again is the simplest nudge. Re-running setup also brings it up:

honeycomb status
honeycomb setup

The helper is safe to start repeatedly; an already-running helper is left alone rather than started twice.

Escalation: If status keeps reporting the helper as unreachable, restart your machine to clear any stuck process, then run honeycomb status again. If it still will not come up, capture what honeycomb status prints and reach out through the support link in Frequently asked questions.

#Recall returns nothing

#Recall comes back empty for something you know you saved

Symptom: honeycomb recall "..." returns nothing, even though you remembered a related note.

Likely causes and fixes, in order:

You are in a different project lane. Honeycomb scopes memory to the project folder you are working in, so a note saved in one repository does not surface while you work in another. Fix: run recall from the same project where you saved the note, or confirm your current project with honeycomb project list.
Meaning-search has not warmed up yet. Until the small local model is ready, recall matches words rather than meaning, so a note phrased differently from your query may not surface. Fix: open the dashboard and check the recall bar for a "lexical fallback" badge. If you see it, either rephrase your query closer to the note's wording, or wait for the model to finish warming and try again.
The note was never written. If you were in read-only mode for that session, nothing new was saved. Fix: confirm you are not in read-only mode, then save the note again.

Escalation: If recall is empty across the right project and meaning-search is confirmed on, open the dashboard's Memories view to confirm the note exists at all. If it is missing there, re-save it.

#Recall results feel thin or worse than usual

Symptom: Recall returns rows, but fewer or less relevant than you expect.

Likely cause: Recall is running in its word-matching fallback because meaning-search is off or a part of the store is temporarily unavailable. The system keeps working, so this is easy to miss.

Fix: Open the dashboard. The health strip names any down subsystem, and the recall bar shows the "lexical fallback" badge when meaning-search was not used. If meaning-search is off, turn it on and let it warm up. If a part of the store is named as down, that is the lead to follow.

Escalation: If the store reports a subsystem as down and it does not clear on its own, capture the dashboard's health detail and reach out through the support link in Frequently asked questions.

#An assistant is not connecting

#An assistant was not wired by setup

Symptom: You ran honeycomb setup but one of your assistants is not picked up.

Likely cause: Honeycomb wires an assistant only when it detects that assistant's own config folder on your machine. If the assistant is installed somewhere non-standard, or not actually installed, it is skipped.

Fix: Confirm the assistant itself is installed, then wire it directly by name:

honeycomb connect <assistant>
honeycomb status

Supported names are claude-code, cursor, codex, hermes, pi, and openclaw.

Escalation: If a confirmed-installed assistant still is not detected, capture what honeycomb status prints and reach out through the support link in Frequently asked questions.

#An assistant is wired but does not seem to recall

Symptom: The assistant is wired per honeycomb status, but it starts sessions without your project context.

Likely causes and fixes:

The helper was down at session start. If the helper was not reachable when the session began, the briefing was skipped and your assistant kept working normally. Fix: confirm the helper is up with honeycomb status, then start a new session.
You are in a fresh or different project. A brand-new project has nothing to recall yet, and a different project has its own separate lane. Fix: confirm your project with honeycomb project list and save a note or two to seed it.

Escalation: If the assistant is wired, the helper is up, and the project is correct but context still never appears, re-run honeycomb setup to refresh the wiring, then start a new session.

#You see duplicate or repeated notices

Symptom: The same start-of-session notice shows up more than once.

Likely cause: On some assistants a notice can be registered in two places at once, briefly spawning two processes.

Fix: Honeycomb already guards against this with a one-time claim, so duplicates should self-resolve. If you keep seeing them, re-run honeycomb setup to normalize the wiring, then start a new session.

Escalation: If duplicates persist after a clean re-run, reach out through the support link in Frequently asked questions.

#Account and switching

#I switched company or team and queries look wrong

Symptom: After switching org or workspace, memory looks like it is coming from the wrong place, or queries fail.

Likely cause: Your active company changed but your sign-in token was still bound to the previous one. Honeycomb detects this drift and re-mints a corrected token automatically at the start of a session.

Fix: Start a new session, which triggers the automatic correction. To confirm where you are:

honeycomb org list
honeycomb workspace list
honeycomb project list

Escalation: If queries stay wrong after a fresh session, switch explicitly to the intended company and team with honeycomb org switch <name> and honeycomb workspace use <name>, then start a new session.

#I already had Hivemind and setup warned me

Symptom: Setup showed a warning about an existing Hivemind install.

Likely cause: Running Honeycomb and Hivemind together is not supported, and the dashboard detected a prior Hivemind install.

Fix: Choose "Proceed with Honeycomb" in the dashboard. It backs up your Hivemind setup first, then moves you over. Because the two share one sign-in, you usually will not even need to sign in again. If the move is interrupted, the dashboard offers to resume or roll back; a half-moved machine is never presented as cleanly done.

Escalation: If the move reports a partial step, the dashboard shows the backup location in plain language. Use the resume or roll-back option it offers rather than deleting anything by hand.

#When to escalate

If a fix above does not resolve the symptom:

Open the dashboard and read the health strip and recall bar, so you know which subsystem is involved.
Run honeycomb status and keep its output.
Reach out through the support link in Frequently asked questions, with the symptom, the dashboard's health detail, and the status output.

#What next

Set things up correctly from the start in Installation.
See the normal flow in Everyday use.
Browse common questions in Frequently asked questions.