Troubleshooting

Sign-in and access

No code arrives. Check the address, the spam folder, and wait 60 seconds before asking again (five per ten minutes). On a developer machine with no RESEND_API_KEY, the code is in the API log and on the sign-in screen. In production, the sending domain must be verified in Resend.

429 with retry_in. A code rate limit. Wait the seconds given.

403 read_only_role. You are an auditor. Ask an owner or admin to change your role, or to do the action.

403 with a permission. Your role lacks that permission; the matrix says who has it.

403 invite_email_mismatch. You opened an invitation while signed in as a different email. Sign out, open the link again and confirm the invited address.

Invitation link says dead. Expired (seven days), revoked, already used, or superseded by a newer invitation to the same address. Ask for a new one.

Ingest

401 not_authenticated from the SDK. The ingest key is wrong, revoked, or the Authorization header is missing. Keys start with sk_stratl_.

The SDK returns spooled. The API address is unreachable from where the code ran, or the API answered 5xx. Records and their originals are in .stratl-spool/; call flush_spool() (Python) or flushSpool() (TypeScript) when the API is reachable. Check STRATL_API_URL and that the machine can reach it.

failed from the TypeScript client. The API refused the record (4xx) so a retry would not help, or the code runs in a browser where there is no spool. The error says which.

409 decision_id_conflict. The decision id already exists in another workspace. Ids are ULIDs; a collision means two workspaces are sending the same ids, which is a client bug.

422 hash_mismatch on an artifact upload. The bytes uploaded do not hash to the path. The SDKs never do this; a hand-written client is hashing different bytes from the ones it sends.

413 artifact_too_large. The default limit is 5 MiB per original (STRATL_ARTIFACT_MAX_BYTES).

Records arrive keyed by trace id or session id. The source did not carry a business subject. Set stratl.subject.type and stratl.subject.id on the root span (OpenTelemetry) or in metadata (Langfuse). Framework packs flag these records.

Custody and integrity

A checkpoint shows the timestamp as failed. No authority answered when the checkpoint was sealed. The checkpoint is signed and stored; timestamping is retried on later ticks against every configured authority. If it stays failed, check that the API can reach the authorities’ URLs.

Verify fails the key check on a bundle from another workspace. Correct behaviour on the portal’s Verify page, which uses this workspace’s key. Use the command-line verifier, which uses the key inside the bundle.

Verify skips the checkpoint checks. The bundle was exported before its checkpoint existed. Press Checkpoint now, then export again.

The API refuses to start: bucket not reachable. With s3-kms, every configured bucket must be reachable at start. Check STRATL_CUSTODY_REGIONS (no quotes) and the AWS credentials; run scripts/check_custody.py.

The API refuses to start: default secret. STRATL_ENV is staging or production and STRATL_SECRET_KEY is unset. Generate one with openssl rand -base64 48.

Take custody: the probe fails on “service cannot delete”. The identity you granted can delete objects. Remove that permission (on AWS, no s3:DeleteObject; on Google Cloud, objectCreator not objectAdmin; on Azure, the custom writer role, not Contributor) and prove again.

Take custody: “this deployment lacks the … custody libraries”. The API was installed without the custody-gcp or custody-azure extra. uv sync --all-extras.

Notices

422 recipient_email_required. Sending by email needs an address: enter it in the dialog, or record a recipient with an email on the notice.

502 email_failed. The email provider refused the message. The notice stays approved; fix the provider and send again.

The notice says its delivery mode is dev_log. The server has no email provider configured; the message was logged, not sent. Only acceptable outside production.

The portal

Every page is blank or shows a sign-in loop locally. The dev server forwards /api to localhost:8000; make sure the API is running there, and that STRATL_WEB_ORIGIN matches the portal’s origin.

The Local dev banner appears in what should be production. STRATL_CUSTODY_BACKEND is not s3-kms. Records are being signed with a key file on the container’s disk. Fix the variable before any real record is written.