Reference
Troubleshooting & FAQ
Common errors and what to do, compatibility between CLI and server versions, and frequently asked questions.
Common errors, what they mean and what to do. Add --json to a failing command to get its error code, and quote any error_id when you report a problem.
Compatibility#
- Upgrade the server first, then the CLI. CLI 0.4.0 needs Weave server 0.4.0 for retryable storage errors, server-side clash routing, resolution points, seeding, partial claims, batch stitches, one-request status and code search.
GET https://api.weave.directory/api/weave/versionanswers the server's version. - Against an older server the CLI falls back where it can (separate stitches instead of a batch, all-or-nothing claims, keyword-only search, no resolution points) and otherwise says the feature "needs a newer Weave server" (
--jsoncodeneeds_newer_server), for exampleweave seedandweave resolutions. - Every agent sharing a checkout must run the same CLI version. An older CLI in the same checkout is safe but slow (it holds the checkout-wide lock for whole commands) and can silently take back a clash a 0.4.0 CLI routed, because rewriting a draft drops its
seenversions. Upgrade them all together. - Resolution-point copies are only made when the author's CLI is 0.4.0 or newer; older CLIs get the author's version kept on the point.
- CLI 0.1.2 and older can't read an operation log that holds a workstream removal; update to 0.1.3 or newer.
Errors and what to do#
| You see | Means | Do |
|---|---|---|
503 unavailable, retryable: true | A temporary storage failure on the server; nothing weaved | Send the same command again. The CLI already resends a stitch up to 3 times; a resend never weaves twice. Log the error_id. |
unreachable | The CLI couldn't reach the server; your stitch is queued | Check the network, then weave push. |
busy / "Another weave command is still running" / "Session '<s>' is busy" | Another command holds the lock (waits up to 30 s) | Retry. With many agents, make sure every CLI is 0.4.0 and use weave serve. |
403 path_out_of_scope | The agent wrote outside its pathScope (paths lists them) | Change only paths in scope, or have an admin widen the agent's pathScope. Decision records need .weave/decisions/**. |
422 secret_detected | A file holds a secret, or has a secret-looking name (findings) | Remove the secret and rotate it; add the file to .weaveignore. An admin may allow it deliberately with --allow-secret <path>. |
403 two_factor_required | You own or administer an organization without 2FA, or the org requires 2FA | Turn on 2FA: avatar → Settings → Account → Set up 2FA. |
403 email_unverified | Your email isn't verified | Settings → Account → Resend verification email. |
403 insufficient_scope | The token lacks a scope (or is limited to repositories for a create) | Issue a token with the scope, without repositoryIds for creating repositories. |
403 forbidden on /api/v1 with an agent token | Agent tokens can't call the platform API | Use a personal access token or a service token. |
403 route_not_allowed | A service token's allowedRoutes doesn't cover this route | Add the route pattern, or use another token. |
401 unauthorized / unauthenticated | No token, a wrong one, or an expired agent token (≤ 24 h) | weave login again, or issue a new agent token. |
404 not_found on /api/weave/<org>/<repo>/… | The server API takes the repository id, not org/name | Use the id from the repository's creation (or GET /api/whoami → repoRefs). |
409 conflict "workstream X is archived; restore it with weave workstream restore X" | The workstream was removed | Restore it, or work elsewhere. |
409 "this repository is archived (read-only)" | The repository is archived | A repository admin unarchives it. |
409 unpromoted_stitches | Removing a workstream with weaved stitches not promoted to its parent | Promote them, or remove with --force. |
403 "workstream main is protected: changes arrive by promotion only" | Direct changes to a protected workstream | Stitch in a child workstream and promote. |
409 attestations_required | A promotion into a protected workstream lacks attestations on the source head | Post the missing attestations, then promote again. |
claim_conflict | A claim target is held by someone else (conflicts) | weave owners <path>, message the owner (weave msg send @owner:<path>), or claim with --partial. |
needs_dependencies | weave promote needs earlier stitches | weave promote <stitch> --to <ws> --with-deps. |
rejected (reject_code, symbols) | The weave check couldn't apply the stitch (an unknown base, a file that would not parse, an op that can't be carried forward) | weave sync, fix the file, stitch again. |
429 rate_limited | Too many requests | Wait for Retry-After seconds; spread work across tokens. |
needs_newer_server / "needs a newer Weave server" | The server predates this feature | Upgrade the server. |
Frequently asked questions#
My stitch said suggested or routed. Did it fail?#
No. A routed change went to its owner, or to the author of newer work it clashed with, as a suggestion. The rest of your stitch weaved. Read the message (weave msg inbox) or weave notices, and decide whether to adjust. If they reject it, a resolution point keeps both versions.
weave stitch succeeded but nothing weaved.#
Everything left in your draft is awaiting its owners (--json: result: "awaiting"). weave status lists them as awaiting <owner>.
weave add didn't pick up a file I edited.#
The file is in another session's draft in this checkout (warning left_out_foreign). See weave drafts --all-sessions and take it over with weave add --adopt <file>. Also check .weaveignore (weave ignore).
weave sync left an edit on disk.#
It is a held edit: you hadn't added it, and it clashes with a newer version. The rest of the file follows the head. Add and stitch it to send it to whoever changed the symbol, or drop it.
A function named something__rp_1a2b3c4d appeared in the code.#
That is a resolution point's temporary copy: both versions are kept until someone picks one. Don't build on it. The owner (or an admin, or the claim holder) runs weave resolve 1a2b3c4d head|copy|edit.
Can two agents edit the same file at the same time?#
Yes. Different symbols never clash. The same symbol: the newer version stays and the other goes to its author as a suggestion. To avoid even that, claim your part first (weave claim … --feature part:<id>).
How do I see who owns a file before I touch it?#
weave owners <path> (or the MCP tool owners). It answers from a local copy at most 15 seconds old; --fresh asks the server.
Why do my agents look like one author?#
They share one person's token. Give each agent its own agent token.
My agent token expired in the middle of a run.#
Agent tokens last at most 24 hours (default 60 minutes). Issue a new one before it expires (POST /api/v1/agents/{id}/tokens) and update WEAVE_TOKEN; drafts on disk are unaffected.
Search doesn't find code I just wrote.#
Semantic search indexes stitched heads only; drafts are found by the keyword half on disk (weave find). After a stitch, the head is indexed in the background within moments (stale: true while it catches up).
Does Weave use git?#
No. Weave stores workstreams, states and changesets itself. It can import from git and mirror a workstream to a git remote when you need one.
The CLI points at an old server or platform.#
A config from an earlier setup can keep it pointed elsewhere. Reset it: weave config platform_url https://www.weave.directory, weave config server_url https://api.weave.directory, then weave init --server https://api.weave.directory in each checkout, and unset WEAVE_PLATFORM_URL / WEAVE_SERVER_URL.
A command ignores my running weave serve.#
Run it with WEAVE_DEBUG_SERVE=1 to see why. Common reasons: a different HOME, XDG_RUNTIME_DIR, server URL or umask from the daemon's, another build of weave, or a command that always runs by itself (it reads stdin, prompts, or runs for long).
How do I report a problem?#
Include the command, its --json output and every error_id. Security issues: see the Security page.