When something looks wrong
Most confusion about a local stack is a missing fact, not a broken service. This page routes a symptom to the one command that produces the missing fact, and then to the chapter that explains it.
Start with the read
oberth status is the first command for almost every symptom: it prints the manifest, the runs and the observed runtime facts side by side. If it prints a failure reason, read that reason before reading any log — it names the service and the phase.
oberth statusSymptom to first command
| What you see | Run this first | What it means |
|---|---|---|
listening unknown, or an observation_* code | oberth doctor --only listener_observation | The observer, not the service, could not see the listener table. Retry from a normal terminal; do not read a timeout as a failure. |
up --wait never returns | oberth logs <service> --once | Readiness is listener plus health. The service's own output says which half failed. |
| A service line shows an exit and a code | oberth logs <service> --once --first-error | The first error of the current run, not the last screen of output. |
auto port unassigned | oberth status --json | Not a failure: port: auto has not been assigned yet. A candidate is verified by binding, not by trusting an empty listener table. |
code_changed_since_start | oberth restart | The process runs older code than the checkout. It is a code fact, not a runtime failure. |
| A stop hits the wrong project, or refuses | oberth down --worktree <path> | Several checkouts share a project name. Identify the checkout explicitly; do not widen the stop. |
| Services still run after a checkout was deleted | oberth worktrees --gone | The identity ledger kept the path. Stop them by worktree or identity; deleting data stays your job. |
| “manifest not found”, or a draft you never adopted | oberth init | An agent may draft a manifest; only oberth init adopt makes it the input to anything. |
| The project lives outside your home directory | oberth up --allow-outside-home after review | The home boundary is a default, not an accident. Read the flag before you pass it. |
What to keep when you ask for help
- The exact command and its exit code, not a paraphrase of what it printed.
oberth status --jsonfrom the same checkout, so the reader sees the same facts.- The first error of the current run:
oberth logs <service> --once --first-error. - What the observer said, if
observationappeared at all: which code, and from which kind of process.