Start with doctor#

Most local surprises are installation surprises. Run weles doctor and read the JSON report: ok, version, node, the bin map, and whether CHROMIUM_PATH or WELES_USE_STOCK_CHROMIUM are set. A wrong or missing managed browser build shows up here before any navigation fails.

Client-side validation refusals#

The client refuses requests before any network traffic when input keys match password, secret, token, cookie, authorization, or proxy-auth patterns. The single exception is resumeToken / resume_token, the approval continuation handle, which is still redacted from every error detail. Key-name matching is not semantic inspection: keep credential material out of input even under innocuous names.

Typed failure codes#

Codes emitted by the client and bridge
Code	Phase	Meaning
`transport-failed`	transport	Ambiguous transport outcome; the library does not retry. Reconcile with an approved status-read channel using the original idempotency key.
`WELES_ENDPOINT_UNRESOLVED`	admission	The Stado forward file is missing, unsafe, or holds an unusable URL; the bridge never falls back to an environment variable.
`DIRECTORY_EXPECTATION_MISMATCH`	admission	The directory cross-check flags disagree with the sealed identity; refusal happens before submit.
`ENTRA_IDENTITY_CONTRACT_MISMATCH`	admission	The directory block does not match the pinned Entra identity for the item, field, or provider; nothing is sent to Weles.
`ENTRA_IDENTITY_MISMATCH`	identity_verification	The signed-in identity does not carry the expected tenant tid, principal oid, and UPN; the change stops before it happens.
`needs_human_approval`	varies	MFA/passkey challenges and unknown-current-password resets pause with an approval resource; resume with skarbiec credential resume --approval <id> --resume-token <token>, never a repeated submit.

Provider effect decides retry safety#

"We did not observe a change" is not "nothing changed": a failed operation whose effect cannot be read reports unknown, never none. Rollback status is reported separately as none, completed, failed, or unknown.

providerEffect values
Value	Retry policy
`none`	Nothing changed provider-side; automatic retry is permitted.
`changed`	A change was observed; run verify or confirm a rollback before any retry.
`unknown`	Effect absent or malformed; never retried automatically — the item is quarantined rather than risked against a password that may already have changed.

Limits#

Hard limits of the public surface
Limit	Value
`approval_id length`	at most 64 characters of [A-Za-z0-9._-]
`resume_token length`	at most 128 characters of [A-Za-z0-9._-]
`Diagnostic message length`	at most 512 characters, no control characters
`execution_host length`	at most 128 characters of [A-Za-z0-9._-]
`action_log_id length`	at most 200 characters of [A-Za-z0-9._-]
`request_id / evidence_digest`	64 hexadecimal characters
`Bridge request schema`	skarbiec.credential-operation.v3 only; v1 and v2 rejected with no alias
`Bearer scopes`	task create, read, and cancel only
`Plaintext HTTP endpoints`	loopback hosts only (127.0.0.1, localhost, ::1)
`Evidence retrieval`	not exposed by the current API
`Automatic retry`	intentionally absent everywhere in the contract

Reporting a failed run#

Open an operational defect on the repository issue tracker with the action-log row ID, worker instance ID, and release coordinate. Never attach recordings or credentials to an issue — see Support.