# 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](../users-manual/03-running-seeder-and-booter.md) |
| **`pretest`** / **`npm test`** failures after edits | [users-manual/07-troubleshooting-and-operations.md](../users-manual/07-troubleshooting-and-operations.md) · [handbook/07-operations-and-development.md](../handbook/07-operations-and-development.md) |
| Environment variables, paths, Corestore locations | [docs/reference/environment-and-posix-appendix.md](reference/environment-and-posix-appendix.md) |
| Broken replication, no peers, swarm topic | [handbook/03-protocol-and-disk.md](../handbook/03-protocol-and-disk.md) · [package-bare-os-protocol.md](reference/package-bare-os-protocol.md) |
| Guest vs **`login`**, vault, **`/.bare/`** | [users-manual/05-home-identity-and-vault.md](../users-manual/05-home-identity-and-vault.md) · [handbook/05-identity-vault-and-hdms.md](../handbook/05-identity-vault-and-hdms.md) |
| Shell, **`man`**, **`help`**, documentation map | [users-manual/06-help-man-and-documentation-map.md](../users-manual/06-help-man-and-documentation-map.md) |
| **`ctx`**, scripts, `/bin` development | [developer-guide/08-testing-and-debugging.md](../developer-guide/08-testing-and-debugging.md) · [developer-guide/02-the-context-object.md](../developer-guide/02-the-context-object.md) |
| Discord bot login hang, 4014, missing `discordJS`, allowlist deny | [developer-guide/21-discord-bots.md](../developer-guide/21-discord-bots.md#troubleshooting) · **`man discord-bot`** |
| CI scripts, verifiers, release checklist | [scripts/README.md](../scripts/README.md) · [docs/release-checklist.md](release-checklist.md) |
| Version skew, feature bits, API alignment | [docs/reference/compatibility-matrix.md](reference/compatibility-matrix.md) · [docs/architecture/KERNEL_CONTRACT.md](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](reference/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](reference/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`](../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](reference/package-bare-os-protocol.md).

---

## Still stuck?

- Search the [FAQ](faq.md) and [glossary](glossary.md).
- 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](architecture/KERNEL_CONTRACT.md)).