Chapter 7 — Troubleshooting and operations

Prerequisites: earlier chapters of this manual. Time to read: about eight minutes.

Boot and swarm issues

Symptom: booter exits on timeout. The booter could not replicate the system drive in time. Typical causes:

the seeder is not running or not reachable on the network;
bootstrap nodes are wrong or blocked—review HYPERSWARM_BOOTSTRAP and firewall rules;
you are using offline LKG mode without a valid local system drive (advanced; see reference docs).

Start the seeder first, wait until it is advertising, then start the booter. For protocol-level failure modes, read Handbook — Chapter 3.

Symptom: “no peers” or empty replication. Confirm both processes use compatible bootstrap configuration (HYPERSWARM_BOOTSTRAP, corporate VPNs, and local firewalls frequently block DHT traffic). Try a clean Corestore path only after you are sure networking is not the root cause, or you may chase ghosts while the real issue was connectivity.

Symptom: boot reaches shell but /proc looks empty or wrong. Some /proc nodes require a minimum ctx API or capability words. Compare /proc/bare_os_features (when present) with the compatibility matrix and the versions printed by bare_os.capabilities during seeding.

Missing binaries or stale image

Symptom: a /bin tool is missing or obviously old under Pear. The bare-os-coreutils workspace must be built before staging or seeding. From the repo root:

npm run build -w bare-os-coreutils

If you changed kernel/ but the seeder still ships an old tree, CI’s verify-kernel-seeder-parity error means packages/bare-os-seeder/kernel/ is out of sync with kernel/—copy or sync per maintainer workflow before release.

Environment variables

There are many BARE_OS_* toggles. Host-side variables are often copied into the guest session so kernels and scripts see a consistent environment.

For a complete list and POSIX-related notes, use Environment variables and POSIX appendix. For a shorter operator cheat sheet grouped by component, see Handbook — Chapter 7.

When debugging, ask whether the variable was set on the host before launching the booter, because the guest only sees what the booter forwards into shellEnv.

Themes and terminals

Symptom: colors or ls --color look wrong. Themes interact with LS_COLORS, ~/.barerc, and the truecolor versus 256-color capability of your terminal emulator. Read the themes documentation and handbook notes rather than chasing random color codes:

CI and contributing

Root npm test runs workspace tests after pretest, which builds artifacts and runs repository verifiers (kernel or seeder parity, ctx API alignment, capability contracts, documentation links, man coverage, compatibility matrix strings, kernel program governance + proc schema + roadmap table checks, Pear import rules, bare manifest smoke).

If gen:bare-catalog:check fails, regenerate the catalog with npm run gen:bare-catalog and commit the JSON. If verify-doc-links fails, fix broken relative .md links in the walked trees.

For a full maintainer-oriented walkthrough, Handbook — Chapter 7 remains the authoritative operations chapter.

Pretest and verifier failures

verify-kernel-seeder-parity — kernel/ and packages/bare-os-seeder/kernel/ must match byte-for-byte. Copy the canonical tree into the package (maintainer scripts or cp -R) after editing kernel/, then re-run pretest.

verify-kernel-capabilities-word-* — The feature roadmap keeps ## Capability word 6…11 checklists as pipe tables with fixed row counts. Do not shrink those tables without updating the matching script under scripts/.

verify-ctx-api-feature-bits / verify-ctx-dts — The ctx API semver and kernel capability documentation must agree with packages/bare-os-protocol and packages/bare-os-booter. Start from the compatibility matrix when bumping versions.

verify-man-coverage — Every kernel/bin/* file must include the BARE_OS_BIN_API pragma and have a man page. Regenerate coreutils outputs after adding a command.

verify-compat-matrix — Strings in compatibility-matrix.md must mention current versions; the script is substring-based, not structural.

verify-pear-no-static-node-import — Pear bundles must not embed forbidden static node: imports; follow patterns in the booter’s Pear entry code.

Pear and module resolution

If pear run fails with missing modules but npm ci at the repo root succeeded, run the npm run os:seeder / os:booter scripts from the root so scripts/ensure-pear-node-modules.mjs mirrors hoisted dependencies into the package node_modules Pear expects. Running pear run manually from a clean package directory without that step is a common source of Cannot find package errors.

Documentation link checks

verify-doc-links walks docs/, handbook/, developer-guide/, scripts/, users-manual/, packages/, kernel/, and root README.md, DOCUMENTATION.md, PEAR-RUN.md. It skips packages/bare-os-seeder/kernel/** because that tree is identical to kernel/**; fix links in kernel/** only. Use relative something.md targets in links so CI can resolve them from each file’s directory.

Previous: Chapter 6 · Next: Chapter 8 — Further reading

6.7 KiB Raw Blame History Unescape Escape