Troubleshooting

Start with the action that failed and the message shown. Keep any request ID when asking your installation operator for help; never include cookies, passwords or email action links.

Invitation expired or wrong account

Account/team invitations last 72 hours. Recovery links last 15 minutes. Request a new link after expiry. A resent workspace invitation replaces the previous one.

Workspace invitations require the bound account and explicit Accept. Sign out of an incorrect account and sign in with the invited account. See Getting access and Team invitations.

No invitation email

Check the recipient address, inbox and spam folder. SMTP acceptance does not guarantee inbox placement. A preparing or unconfirmed delivery is not a confirmed send.

An operator should check reachability from both Keycloak and the API, TLS hostname/certificate validation and credentials. After repairing the transport, use an explicit resend and respect the cooldown. See SMTP and local email.

Settings are read-only or a workspace disappeared

Check your current workspace, role and archive state. Editor/Viewer cannot change project or team settings. Workspace archive blocks writes to all its projects. Project archive blocks that project’s writes.

Membership removal and role reduction take effect on subsequent requests. Ask a current workspace manager to confirm access; signing in repeatedly does not restore removed membership.

Your change conflicts with newer data

A 409 can indicate an outdated version or conflicting operation. Refresh, inspect the latest state and review your change before resubmitting. Do not automatically force a mutation using the new version.

An idempotency key cannot be reused with different input. Keep it for a retry of the same uncertain creation; use a new key for a genuinely different request.

A language cannot be deactivated

The source is always active. For a target, check Dependent languages in the error. Active and inactive languages both count as dependents.

Change each listed language’s fallback to another active destination, then retry deactivation. See the worked example in Fallback chains.

Language code or fallback rejected

Use a registered, supported language code. Reactivate an existing inactive language instead of adding it again.

A fallback must point to another active language in the same project and lead to the source without a cycle. Regional codes do not create implicit links.

The API requires its database and bounded identity validation. A service failure returns an error rather than extending unverified access. Restore the failed dependency and retry after recovery.

For a local setup, verify origins and ports, wait for Keycloak startup and run the explicit pnpm auth:configure command after configuration changes. Check Docker-to-host backchannel reachability if device revocation is delayed.

Existing local data with missing configuration

Restore the matching environment configuration. Do not generate new credentials against an existing volume or remove that volume to repair authentication. A changed session encryption key also requires a planned session reset.

Documentation search has no results

Pagefind searches the built static site. Run pnpm build:docs and pnpm preview:docs for a local check. For a deployed site, confirm that its search index and hashed assets came from the same complete build as the HTML.

A translation remains Missing

Empty, cleared and whitespace-only values are Missing. Values in other languages never fill the cell automatically. Check the selected language and save a direct value. A project’s source language does not require a value.

An ICU value or contract is rejected

Check the error’s language and reason. Every filled value must use exactly the key’s shared parameters with compatible text/number usage; select/plural branches require other. For a contract change, use Values and atomic corrections to correct all affected active languages together. Reactivate an inactive language before changing its value. No changes commit when any language fails.

A translation edit conflicts

Your draft is preserved. Compare Current saved value or Current key definition, explicitly keep the draft with the current version, then save again. Do not repeatedly overwrite without reading the current record. A duplicate key name remains reserved even when its key is archived. See conflicts and history.

Import is blocked or remains queued

A queued transfer needs the worker and PostgreSQL. Check readiness before retrying. A preview with errors cannot be applied: correct its locale, file identity, parameter mapping or unsupported structure, then regenerate. A conflict requires a new preview and approval; the old import leaves no partial content. See import recovery.

Export needs an identity or parameter mapping

Expand Correct export options on the failed job. Choose a valid native identifier and positional argument order, or use the original import group. Gettext plurals require a plural message ID; XLIFF needs source text. Unsupported expressions fail explicitly. The format matrix lists each supported subset.

A used tag cannot be deleted

Follow its linked-key count on Tags. Remove active-key links first; archived-key links require an explicit key restore before editing. Owner/Admin can then delete the unused tag. Renaming and deleting tags are not Editor permissions.

A download or preview has expired

Files and previews last 24 hours. Create a new job; the 30-day job summary contains no recoverable file or translation body. Removing a user’s membership immediately removes their access to previous jobs and downloads.

Branch comparison or merge stopped

A changed source/target invalidates the preview. Compare again and review new choices; old resolutions are not silently reused. Resolve every conflict and integrity issue. Restore archived target keys or activate inactive target languages before editing their content. A failed merge does not partially commit.

Branch deletion is blocked

Main is protected. Archive a non-main branch, then complete or cancel its unfinished transfers and branch operations. Confirm its exact name. Shared history remains available to other branches; deletion is irreversible.

Branch jobs remain queued

Check the worker readiness endpoint and run the separate queue migration after the application migration. Temporary failures expose explicit retry; access or stale-content failures require a new operation.

Requests are rate limited

A 429 response means the caller reached an API request limit. Wait for the returned Retry-After duration before retrying and reduce polling frequency. Background work can continue while status requests are throttled; inspect the existing job instead of creating duplicate work. See API limits.

A release cannot be published

Check its validation report. Preview permits unresolved requested values; Production requires every requested key/language to resolve directly or through explicit fallback. The exact package and version target must first be active on both Preview nodes for this distribution. Confirm the Preview test explicitly.

Publication is partially active

Do not start another publication or erase its decision. Restore the unavailable node and choose Retry operation. The worker completes the same committed revision. A policy revocation is likewise incomplete until both nodes acknowledge it. See recovery.

Publication review became stale

A channel change or expired review returns a conflict. Discard the review and create a new one; previous confirmation does not approve a changed catalog. A release build conflict means the branch changed before capture. Refresh and prepare a reviewed new release.

Rollback is blocked

At least one affected application version has no compatible remaining publication. Publish a corrected release first. Rollback withdraws one publication, never all newer publications or branch edits.

Operational diagnostics

Monitoring and error references explains safe request references, private logs/traces and failure recovery. Optional SDK diagnostics remain off unless the application explicitly configures a write-only diagnostic key. A reporting outage does not change verified translations or the publication commit boundary.

Translation assistance

For authentication/model/language failures, check the configured connection and exact capability catalog. For Outcome unknown, a request may already have been charged: review before approving another attempt. For Apply conflicts, compare current source/target content and create a new preview if the source changed. Assistance recovery explains reservations, expiry and vault incidents.