Cortex support & feedback
Send a message about Cortex ✉️
On the hosted service, tell us which organisation’s tenant you are in, what you were doing, and what you saw — a screenshot of the message helps more than a description of it. We run the servers, so there are no logs for you to collect.
On a self-hosted instance, include the version you are on and the output of docker compose logs api around the failure.
A mailbox says “Reconnect needed”
The grant expired or was revoked at the provider. Reconnect the account and it resumes; Cortex backs off between retries rather than hammering a failing account.
A mailbox is stuck on “Syncing…”
Usually a wedged worker rather than anything to do with the mail account. On the hosted service, write to us and we will clear it. On a self-hosted instance, check the worker directly at /api/diagnostics/worker, which also reports stalled jobs; restarting the worker container clears it.
On a self-hosted instance
Self-hosting is arranged with us, so we will have set the instance up with you. These are the problems that still come up afterwards.
The stack won’t come up: network web not found
The production stack joins an external Docker network rather than creating one, so it has to exist first:
docker network create web
Everything started, but I can’t reach Cortex
By design, the production stack publishes no port on the host — it expects a Cloudflare Tunnel in front, which then becomes the only way in, including for the admin console. If you want to reach it directly on the LAN instead, publish the web container’s port 80 yourself (for example ports: - "8090:80") and terminate TLS somewhere.
It refuses to start and prints a configuration warning
That is the production safety gate, and it lists exactly what it objected to — read the bullets it prints. The usual causes are a SESSION_SECRET shorter than 32 bytes, database credentials left at their defaults, a missing CREDENTIALS_ENCRYPTION_KEY, or an OAuth redirect base that is not https. It fails closed on purpose: none of those are safe to run with.
One easily-missed detail: the database password is embedded in the connection string, so characters like / @ : # ? break it. Use something hex or alphanumeric.
Port 5432 is already in use
You started the development stack by accident — a bare docker compose up picks the dev file, which publishes the database and Redis and seeds demo data. Always pass the production file, or export it once:
export COMPOSE_FILE=docker-compose.prod.yaml
Your production data is unaffected — it lives in the directory you set as DATA_ROOT, not in the dev volumes.
On a Synology NAS: bind mount failed, or the deploy aborts
DSM does not create bind-mount directories for you, so make them before the first start:
mkdir -p $DATA_ROOT/postgres $DATA_ROOT/redis
If you are deploying through Portainer, DATA_ROOT must be an absolute path — a relative one puts your database inside Portainer’s own stack directory, where you will not think to look for it.
How do I actually back this up?
Back up the DATA_ROOT directory — that is your instance, database included — or take a pg_dump. The built-in Git export and JSON export are useful, but they are content exports, not disaster recovery; restoring one merges content into a workspace rather than rebuilding a server. The FAQ explains the difference.
Keep your CREDENTIALS_ENCRYPTION_KEY with that backup. Restore the data without it and every stored credential — mailboxes, tokens, two-factor seeds — becomes unreadable.
More questions? Read the full Cortex FAQ →
Cortex / Privacy Policy (hosted service) / red8.io privacy for Cortex / Terms of Service
