How-to guide
Troubleshooting
The setup blockers operators hit most, as symptom / likely cause / fix. Most are configuration or credential issues that resolve in one step once you know where to look — Workbench fails loud and names the cause in its logs and audit trail rather than degrading silently.
Boot & secrets
The container won't start, and the logs mention the master key
Likely cause — WORKBENCH_MASTER_KEY / WORKBENCH_MASTER_KEY_FILEis unset, or the value doesn't match the one the existing data volume was encrypted under. The master key is the root of at-rest encryption; Workbench fails closed without it.
Fix — On a fresh install, set the key (getting started shows the Docker-secret form). On an existing volume it must be the same key — a different or missing key cannot unwrap the workspace seed and the data is unrecoverable, so restore the key from your secret manager. This is why the key must be backed up outside the data volume.
Activation is rejected after a redeploy with an instance-mismatch error
Likely cause — The identity volume (/var/lib/arq — instance_id + install_secret) was lost or recreated, so the deployment's identity changed. Activations are bound to that identity by design (anti-reuse).
Fix — Restore the identity volume from backup so the original instance_idreturns. If it is genuinely gone, the activation can't be re-bound — request re-issuance. Back up the identity volume separately from the data volume.
Licensing
License upload / activation fails or the wizard is stuck
Likely cause — The license file is malformed (trailing whitespace from a copy-paste is the usual culprit), its signature doesn't verify against the embedded key ring, or it was issued for a different deployment.
Fix — Re-download the file and upload it as-is (don't edit it). For air-gapped installs use the offline activation exchange rather than a direct upload. A genuine deployment-identity mismatch needs re-issuance.
API access (curl)
Mutating API calls return 403 / a CSRF or session error
Likely cause — The request is missing the session cookie or the CSRF header. Every mutating route (license activation, registration, integrations) needs the admin session cookie and the matching CSRF token.
Fix — Log in capturing the cookie jar (-c /tmp/wb.cookies), reuse it on later calls (-b /tmp/wb.cookies), and pass the CSRF token pulled from that jar:-H "X-Arq-CSRF: $(grep arq_workbench_csrf /tmp/wb.cookies | awk '{print $7}')" . The CSRF cookie is set at login, so log in first.
Image verification
cosign verify aborts with a non-zero exit
Likely cause — The resolved digest or the certificate-identity / OIDC-issuer arguments don't match, or the image genuinely isn't the signed release.
Fix — Re-resolve the digest and re-run with the exact identity regexp and issuer from Verify the image. Never run an image whose signature does not verify — treat a failure as a supply-chain signal, not a formality.
Integrations
Ticket push fails with an auth error
Likely cause — The integration credential (GitHub PAT, GitLab token, or Jira API token) expired, was rotated upstream, or lacks the required scope (Issues: read & write, GitLab api, or the Jira project permissions).
Fix — Workbench records the failure in its audit log as ticket.dispatch.failure with a closed failure_kind (auth failures classify as class_auth_failed). Rotate the token on the Integrations page and re-check scopes — see Connect a ticket system. Dispatch is idempotent, so re-running after the fix won't duplicate tickets.
Collection (Signals)
Signals collection fails with permission errors
Likely cause — The role Signals connects with lacks pg_monitor-grade privileges. Signals also rejects superuser and replication roles, so an over-privileged role won't work either.
Fix — Grant the least-privilege monitoring role: GRANT pg_monitor TO <role>;. The error log names the specific view it couldn't read, so it usually resolves in one step. Full role setup is in the Signals docs.
Hit something not covered here? Tell us — Workbench's audit log usually carries a closed error code that points straight at the cause.