47 lines
3.7 KiB
Markdown
47 lines
3.7 KiB
Markdown
# 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) |
|
||
| 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)).
|