Troubleshooting (router)

Use this page to jump to the right doc for your situation. Symptom-first paths point at deeper material; the user manual’s operations chapter remains the primary step-by-step for day-to-day issues.

Quick routes

Symptom or goal	Start here
Seeder or booter won’t start; Pear vs Node confusion	users-manual/03-running-seeder-and-booter.md
`pretest` / `npm test` failures after edits	users-manual/07-troubleshooting-and-operations.md · handbook/07-operations-and-development.md
Environment variables, paths, Corestore locations	docs/reference/environment-and-posix-appendix.md
Broken replication, no peers, swarm topic	handbook/03-protocol-and-disk.md · package-bare-os-protocol.md
Guest vs `login`, vault, `/.bare/`	users-manual/05-home-identity-and-vault.md · handbook/05-identity-vault-and-hdms.md
Shell, `man`, `help`, documentation map	users-manual/06-help-man-and-documentation-map.md
`ctx`, scripts, `/bin` development	developer-guide/08-testing-and-debugging.md · developer-guide/02-the-context-object.md
CI scripts, verifiers, release checklist	scripts/README.md · docs/release-checklist.md
Version skew, feature bits, API alignment	docs/reference/compatibility-matrix.md · docs/architecture/KERNEL_CONTRACT.md
`curl` / `wget` exit 127 (“unavailable in this session”)	Stock booter must expose `ctx.bareOsRunCurlCli` / `ctx.bareOsRunWgetCli`; upgrade `bare-os-booter` and match `ctx` API in compatibility-matrix.md. `BARE_OS_DELEGATE_ALLOW` excluding `curl`/`wget` does not disable HTTP fetch — only host delegation order changes.

“Factory reset” local state

Seeder and booter persist under defaults such as ~/.bare-os/ (see the environment appendix). Deleting those directories wipes local Hyperdrive state—treat that as intentional data loss for development.

Offline / LKG boot

Peer assumptions and BARE_OS_OFFLINE_LKG_BOOT are summarized in compatibility-matrix.md under Peer assumptions.

Blind bootstrap / HyperDHT hints

Host operators can surface non-secret bootstrap material via BARE_OS_BLIND_BOOTSTRAP_URL / BARE_OS_BLIND_BOOTSTRAP_JSON (mirrored under /proc/bare_os_bootstrap). The seed RPC registry includes dht_bootstrap_hint and blind_peer_topology_v2 for Holepunch-aligned operators; CI asserts those short names stay registered (packages/bare-os-protocol/test.js). If boot fails before peers attach, verify seeder bare_os.capabilities and your relay/DHT configuration against package-bare-os-protocol.md.

Still stuck?

Search the FAQ and glossary.
Run npm run pretest to catch stale links and contract drift.
Open an issue with booter boot steps from /run/bare-os/boot.json when relevant (see KERNEL_CONTRACT).

3.7 KiB Raw Blame History Unescape Escape