Skip to main content

Troubleshooting

Use this page to diagnose common deployment and administration issues.

Cannot register a new user​

After the first account is created, self-registration requires an invite.

Check:

  • Was the first user already created?
  • Is the invite token complete and unexpired?
  • If the invite has an email, does it match the email being used to register?
  • Was the invite revoked or already accepted?
warning

The first registered user becomes the first organisation owner and server admin. If the wrong person created the first account, treat it as an administrative incident and correct ownership before inviting the wider team.

Server setting saves but behavior does not change​

Most server settings require a backend restart.

Check:

  • Did you restart the backend after saving YAML?
  • Is the field marked with an environment override?
  • Is the matching environment variable set in .env, Docker Compose, or the host environment?
  • Are you editing the YAML file shown in Server Settings?

Environment variables override YAML. For non-secret server config, remove or change the override and let YAML control the setting.

Users are unexpectedly signed out​

Session cookies depend on APP_SECRET.

Check:

  • Was APP_SECRET changed?
  • Is APP_SECRET set to a stable deployment-specific value?
  • Is session_cookie_name stable?
  • Is session_cookie_secure: true being used only over HTTPS?
  • Did the browser receive cookies from the public app origin?

Changing APP_SECRET invalidates existing sessions by design.

Uploads fail​

Check:

  • Is the file larger than upload_max_bytes?
  • For profile images and logos, is the file a valid raster image?
  • Is the upload storage path writable by the backend?
  • Is the backend data volume mounted and persistent?
  • Is the user allowed to perform that upload action?
warning

If uploaded files disappear after a deploy, check the backend data volume immediately. The database may still reference files that were stored on a deleted or unmounted filesystem path.

Uploaded file opens as 404​

Check:

  • Is the user signed in?
  • Does the user belong to the attachment's organisation?
  • Is the attachment owned by the current user or a member of the active organisation?
  • Does the file still exist under the configured upload storage path?
  • Was the upload volume restored with the database?

Server admins can read attachments for administration, but regular users need attachment ownership or organisation membership.

Export is empty or missing expected records​

Check:

  • Are you in the intended active organisation?
  • Are records scoped to a restricted project you cannot read?
  • Are records owned by another user and not shared through a readable scope?
  • Are you expecting a full infrastructure backup rather than a user-accessible JSON export?

Exports follow user and scope permissions. Use database and volume backups for complete restore coverage.

Restricted project content is visible or editable​

Check project visibility and grants.

Open projects allow organisation members to read and update project work. Restricted projects require explicit direct or group grants, except for organisation admins, server admins, and the project lead.

For restricted projects:

  • Viewer can read.
  • Member can read and write.
  • Lead and admin can manage.
  • Organisation owners and admins can manage regardless of direct grant.

AI web search is unavailable​

EXA_API_KEY controls optional web search and scrape tools.

Check:

  • Is EXA_API_KEY configured in .env or the environment?
  • Was the backend restarted after adding it?
  • Does your organisation permit external web search in AI workflows?

If Exa is not configured, AI can still use internal memory, docs, tickets, decisions, risks, and snapshots.

AI calls fail​

Check:

  • Is OPENAI_API_KEY configured?
  • Are openai_reasoning_model, openai_fast_model, and openai_embedding_model in tow.yaml valid for your provider?
  • If using openai_base_url, does that provider support the configured models and input types?
  • Did environment overrides prevent YAML changes from taking effect?
  • Is the backend able to reach the model provider network endpoint?

OpenAI Responses API calls use store=false. This controls provider-side response storage but does not remove the need to protect prompts, uploads, and outputs as company data.

The in-app Documentation link is controlled by VITE_DOCS_URL.

Check:

  • Is VITE_DOCS_URL set to the deployed Docusaurus URL?
  • Was the frontend rebuilt after changing a VITE_ value?
  • Is the docs service running if you use the Docker docs profile?
  • Are DOCS_SITE_URL and DOCS_BASE_URL correct for the docs deployment?

The Docusaurus docs site is separate from the authenticated in-product docs wiki.