# Troubleshooting & FAQ > Common errors and what to do, compatibility between CLI and server versions, and frequently asked questions. > > Source: https://www.weave.directory/docs/troubleshooting 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/version` answers 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"** (`--json` code `needs_newer_server`), for example `weave seed` and `weave 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 `seen` versions. 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 '' 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 `. | | `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///…` | 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 `, message the owner (`weave msg send @owner:`), or claim with `--partial`. | | `needs_dependencies` | `weave promote` needs earlier stitches | `weave promote --to --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](https://www.weave.directory/docs/working-together#resolution-points) 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 `. ### `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 `. 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:`). ### How do I see who owns a file before I touch it? `weave owners ` (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](https://www.weave.directory/docs/agents#one-token-per-agent). ### 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](https://www.weave.directory/security) page.