Operations and troubleshooting
Inspect a running node, diagnose connectivity and retain identity and data.
Check the installed workspace
~/.weave/bin/weave node status --json
~/.weave/bin/weave doctor --json
~/.weave/bin/weave node logs --lines 50 --json
~/.weave/bin/weave dht peers --jsonDoctor requires the installed binary, a valid persisted identity, a running node, correct owned service supervision when configured, at least one live Kademlia peer, and an authenticated provider announce/find round trip. Its lookup can use the node's local DHT cache. Doctor does not prove remote propagation or cross-machine sparse replication; use a second computer and verify actual bytes for that.
Check ok, the failed checks fields and errors. Share diagnostics without copying identity files, signing keys, unrelated configuration or private data.
Start and stop
~/.weave/bin/weave node stop --json
~/.weave/bin/weave node start --jsonThese commands retain identity and data. An owned installed service is stopped/started through its manager; detached mode is managed by the native runtime. A stopped node cannot serve new remote reads. Rerun npx joinweave@0.1.1 to repair an owned installation after addressing the reported problem; conflicting or modified files are preserved.
Common failures
| Symptom | What to check |
|---|---|
weave is not found | Use ~/.weave/bin/weave; open a fresh shell after consenting to --path |
| Missing native optional package | Remove --omit=optional/optional-dependency exclusions from the install; no compile fallback exists |
| Unsupported platform or loader error | Check the platform matrix, glibc and ARM OpenSSL 3 runtime |
| systemd user session unavailable | Use a working user session or install with --no-service for detached mode |
| Node has zero Kad peers | Check DNS and outbound access to dht1/2/3.weave.earth:4001; inspect node logs |
| Service is not supervising the runtime | Use node stop followed by node start and inspect the returned service status |
| Writer-key conflict | Reuse the correct existing pin or choose a fresh alias for a different key; do not overwrite local data |
| Provider not found | Confirm the exact writer key, producer's announcement and running node; names are not global lookup identifiers |
| Sparse request fails | Check that selected blocks exist, producer connectivity, relay capacity and the requested wait bound |
MCP cannot start npx | Use the absolute npx path accessible to the GUI client and restart it |
| npm minimum release age rejects a package | Respect the configured policy and retry when eligible; do not disable it for the example |
Workspace and identity
WEAVE_HOME selects a dedicated absolute workspace. Pass the same value to the installer, CLI and MCP server. The default is ~/.weave, with config, keys, stores and logs. The visible ~/Weave folder is separate; it is not an automatic filesystem mirror.
The generated identity is a local Ed25519 keypair with a did:oas:weave:agent:... identifier. It is persisted privately with 0600 key-file permissions, not automatically enrolled in an account or placed in an OS keychain. Reusing the workspace preserves identity. Invalid or insecure identity state is refused rather than silently replaced.
Uninstall safely
npx joinweave@0.1.1 uninstall --yes --jsonThe installer removes owned integration and stops the node, keeping identity and stored data. ~/Weave remains. Review warnings about modified entries. --purge explicitly removes the dedicated workspace, including identity keys; it is not a routine troubleshooting step.
