Troubleshooting and error codes

Start with doctor and status

wiele doctor
wiele status

doctor checks the saved session, the API, the background process, free disk space and the checkout in the current folder. status shows local changes, the remote head, pending push or pull work and, for each problem, the command that fixes it. Run the fix it names before anything else.

Reading an error

Every error has a stable code, a message and usually a next step:

error: Missing tracked files require explicit deletion approval (PRECONDITION_REQUIRED)
next: Review wiele status, then push with --delete

With --json, the same error is {"ok":false,"error":{"code":...,"message":...,"retryable":...,"nextActions":[...]}}. retryable: true means running the same command again can succeed.

Common problems

"No saved session for this API origin"

You're not signed in on this machine, or you signed in against a different --api-url. Run wiele login.

"Credential storage is unavailable or insecure"

The OS keychain is locked or missing, or a --credential-file fails the safety checks. Unlock the keychain, or use a session file in an owner-only folder:

mkdir -m 700 ~/.wiele
wiele login --credential-file ~/.wiele/session.json

The path must be absolute and the folder must allow no access to other users.

You ran login from a script or an agent. Use wiele auth start --email ADDRESS --json, then pipe the code into wiele auth verify --challenge ID --code-stdin.

"Select an organization"

You belong to several organizations and none is picked. Run wiele org use SLUG, or pass --org.

"is not a Wiele checkout"

The command needs a checkout and the folder isn't one. cd into the checkout or pass --directory. wiele checkout list shows the checkouts on this machine.

A push fails with `HEAD_MOVED` or `PUSH_CONFLICT`

Someone else pushed first. Your local files are unchanged. For HEAD_MOVED, run wiele pull and push again. For PUSH_CONFLICT, see Conflicts and merging.

A push says "Push is still pending"

The upload or commit took longer than the wait. The push is saved; run wiele push again to resume it. wiele push --abandon drops the saved push and keeps your files.

A pull did not finish

RECOVERY_REQUIRED with "A previous pull did not finish applying files" means a pull was interrupted. Keep both versions of everything first, then pull again:

wiele checkout recover --export-to ~/wiele-recovery
wiele pull

Missing files and `--delete`

Wiele never deletes remote files because they disappeared locally. If you meant to delete them, push with --delete. If not, run wiele pull to get them back.

`PAYMENT_REQUIRED`

The organization has no subscription in good standing, or the plan has no room for another member. Reading keeps working. An owner or admin runs wiele billing status, then wiele billing checkout --plan PLAN or wiele billing plan --plan pro.

Background sync stopped

Run wiele daemon logs to see the last code, fix the cause, then enable the mode again. See Background sync.

Case-only name clashes on macOS

macOS treats Notes.md and notes.md as the same file. If both exist remotely, fetching fails with LOCAL_PATH_COLLISION. Rename or remove one of them from a case-sensitive file system, such as a Linux machine.

Error codes

Code	Meaning	What to do
`INVALID_REQUEST`	The command line or request is malformed, such as a missing flag or a bad value.	Run the command with `--help`. Under `--json`, run it once without `--json` to see the exact problem.
`REQUEST_TOO_LARGE`	The request is over a size limit, such as more than 100 paths in one `write`.	Split the request, or use `fetch` and `push` for large changes.
`AUTH_REQUIRED`	No session is saved for this API origin, or the server did not accept it.	Run `wiele login`.
`AUTH_EXPIRED`	The session expired, or sign-in could not finish.	Run `wiele login` again.
`OTP_INVALID`	The sign-in code is wrong or expired, or there were too many wrong codes.	Request a new code. After three wrong codes, wait up to an hour.
`RATE_LIMITED`	Too many requests of one kind, such as sign-in codes, organizations or workspaces created.	Wait and retry. The error says which limit applies.
`ACCESS_DENIED`	You can see the target but your role does not allow this action.	Ask an admin for the role you need. `wiele access explain` shows your role and where it comes from.
`NOT_FOUND`	The target does not exist or you cannot see it. Also returned for a version removed by retention and for search, which is off.	Check the name, path and organization. Pick a newer version for a removed one.
`SOURCE_ACCESS_REQUIRED`	Someone you invite to a branch needs read access to its files first.	Grant access to the files in the same invitation, or before it.
`POLICY_CHANGED`	Access rules changed after the request was prepared, so it no longer applies as planned.	Read the current state again, such as a fresh merge plan or policy epoch, and retry.
`POLICY_CHANGING`	An access change is being applied in the organization.	Retry in a moment.
`MAIN_PROTECTED`	Live uploads cannot write to main.	Create a branch with `wiele branch create` and switch the checkout to it.
`HEAD_MOVED`	The branch changed after you read it, so the push, merge or draft is stale. Local files are unchanged.	Run `wiele pull`, then push again. For a merge, save a new draft with `wiele conflict list BRANCH --save NEW_FILE`.
`PUSH_CONFLICT`	Another push changed the same files since your last pull. Nothing of yours was published.	Run `wiele pull --keep-local`, fold in the other changes, then push again.
`MERGE_CONFLICT`	The branches changed the same files differently.	Resolve each conflict with `wiele conflict resolve`, then approve the merge.
`BRANCH_BUSY`	Another checkout holds the branch's live writer, or another publication is running.	Wait, or run `wiele live disable` in the other checkout.
`BRANCH_EXISTS`	A branch with this name already exists.	Choose another name.
`INVALID_BRANCH_NAME`	The branch name is invalid or reserved.	Choose another name. `main` and command words such as `create` or `list` are reserved.
`INDEX_NOT_READY`	Search has not indexed the branch head yet.	Wait for indexing, or run `wiele search index`.
`SEARCH_SCOPE_TOO_BROAD`	The search covers too many separately shared folders.	Pass `--path` with a narrower folder.
`UNSUPPORTED_PATH`	A path is too long, too deep, has characters Wiele doesn't allow, or the server refused it.	Rename the file or folder.
`FILE_TOO_LARGE`	The file is over the 512 KiB limit for `wiele write`.	Put larger files in a checkout and push them with `wiele push`, up to 10 GB per file.
`PRECONDITION_REQUIRED`	The command needs an explicit confirmation, such as `--delete` for missing tracked files or a precondition for `write`.	Review `wiele status`, then pass the flag the error names.
`IDEMPOTENCY_CONFLICT`	The idempotency key was already used for a different request.	Use a new key for a new request. Reuse a key only to repeat the same request.
`IDEMPOTENCY_EXPIRED`	The idempotency key is too old, or dated more than 5 minutes in the future.	Run the command again without `--idempotency-key`.
`OPERATION_PENDING`	The work was accepted and is still running after the wait ran out.	Run the same command again, with the same `--idempotency-key` if you passed one. `wiele push` resumes the saved push.
`CANNOT_CANCEL`	The operation is already committing and can no longer be cancelled.	Wait for it to finish, then pull.
`CAPACITY_UNAVAILABLE`	A service or local resource is unavailable, such as the API, the OS keychain, the disk or billing, or a request is over a fixed size limit, such as an 8 MiB diff.	Retry later. For keychain errors, unlock it or use `--credential-file`. For a size limit, narrow the request: a smaller folder or fewer revisions.
`PATH_OCCUPIED`	The destination already exists, such as a folder that is already a checkout.	Pick a new destination, or use `wiele pull` to update an existing checkout.
`SHARING_CHANGE_UNSUPPORTED`	A move would put a file under different sharing rules.	Copy the file to the new place and delete the old one in separate steps.
`CURSOR_INVALIDATED`	The listing changed and the page cursor no longer applies.	Start the listing again from the first page.
`LOCAL_PATH_COLLISION`	Two paths differ only by letter case, and this file system can't hold both.	Rename one of them.
`LOCAL_EDIT_RECOVERED`	An editor changed a file while `pull` replaced it, so the pull stopped partway. The edited bytes are kept in a recovery file.	Open the recovery file the error names before anything else. Don't repeat the pull until you've saved what you need; `wiele status` shows the next step.
`RECOVERY_REQUIRED`	The checkout or the background process needs attention, such as a pull that did not finish.	Run `wiele status` and the fix it names, or `wiele checkout recover --export-to NEW_FOLDER`.
`UNSUPPORTED_FILESYSTEM`	The checkout holds a symlink or special file, or the file system lacks a feature Wiele needs.	Use a local APFS or ext4 folder without symlinks.
`UNSUPPORTED_REPOSITORY_FORMAT`	The workspace uses a storage format this command does not support.	Contact hello@wiele.io.
`CLIENT_UPGRADE_REQUIRED`	The API answered in a way this CLI does not understand.	Update with `npm install -g wiele` and check `--api-url`.
`DIRTY_CHECKOUT`	Local edits are in the way, such as a file changed during capture or local and remote edits at the same path.	Push or move your edits, or use `wiele pull --keep-local`.
`CHECKOUT_TARGET_CHANGED`	The remote file or folder behind the checkout moved or was replaced.	Keep your edits and fetch a new checkout.
`NETWORK_UNAVAILABLE`	The request did not complete.	Check the network and retry the same command.
`INTERACTION_REQUIRED`	The command needs an answer it cannot ask for, such as a sign-in code without a terminal or an organization choice.	Use `wiele auth start` and `wiele auth verify --code-stdin`, or pass `--org` or run `wiele org use`.
`INTEGRITY_FAILED`	Downloaded bytes did not match their recorded hash.	Retry. If it repeats, contact hello@wiele.io.
`OPERATION_CONFLICT`	The request conflicts with the current state, such as settings changed meanwhile or a subscription that already exists.	Read the current state and retry. The error's next line says what changed.
`PAYMENT_REQUIRED`	The organization has no subscription in good standing, or its plan has no room for another member.	An owner or admin runs `wiele billing checkout` or `wiele billing plan`. Reads keep working.
`WRITE_CONFLICT`	A `write` precondition failed: the path changed since you read it. Nothing was written.	Read the file again, fold in the change and write with the new hash.

Exit codes

Code	Meaning
`0`	Success.
`1`	The command failed with one of the error codes above.
`2`	The command line could not be parsed.

Still stuck

Email hello@wiele.io with the command, the error code and the output of wiele doctor --json. Don't send session files, tokens or sign-in codes.