Skip to main content
Most plamotrack issues fall into a handful of categories. This page covers the most common ones with the quickest fixes.
You’re reaching the instance by a name it doesn’t know. Add the name to ALLOWED_HOSTS in .env (or set PUBLIC_BASE_URL if you’re behind a proxy), then run:
Nothing is written or lost while the setting is wrong — fix the line and restart.
You’re behind an HTTPS proxy or Cloudflare Tunnel but haven’t set PUBLIC_BASE_URL in .env to your https:// address. Set it, then run:
Reads still work; only writes are blocked until this is set.
Run docker compose ps to find the unhealthy service. If it’s migrate, check its output:
The API deliberately won’t start if migrations fail, so a stopped deploy here means your database is still intact.
You installed with git clone, and your .env is older than the current Compose files: it has no COMPOSE_FILE line, so Docker Compose looked for a published image instead of building plamotrack from your checkout. Nothing was changed. You can move the installation onto the release files, or keep building from Git by adding these two lines at the top of .env:
Then run:
Set WEB_PORT in .env to any free port (e.g. 9090), then restart:
You skipped the cp env.example .env step during installation. Create the file first:
Then open .env, replace change-me with a real password, and run docker compose up -d --no-build --wait.
You changed POSTGRES_PASSWORD in .env after the database was already created. Postgres only reads that value when it initialises an empty data directory — it does not update on restart.You have two options:
  • Set it back to the original value and restart.
  • Start fresh: run docker compose down -v (this deletes the database), then restore from a backup. See Backups.
Reset it from inside the API container — this never goes over the network:
It prompts for a new password, sets it, and signs all browsers out. Access tokens are not affected — revoke any you no longer trust from Settings once you’re back in.
Make sure you’re using the URL with a trailing slash (/mcp/ not /mcp).If you have a proxy in front of plamotrack, check that it has response buffering disabled for the MCP endpoint and doesn’t impose a short read timeout. MCP is a streaming protocol — a buffering proxy holds the response instead of passing it on, and the client hangs silently. The bundled nginx configuration in frontend/nginx/default.conf.template is a working reference for the correct settings.
Cloudflare’s 125-second timeout fired on a large, slow request before the response headers arrived. The import still completed on the server — check plamotrack to confirm. MCP and other streaming requests are unaffected by this timeout.
Your proxy or Cloudflare connector isn’t listed in TRUSTED_PROXIES in .env, so every visitor appears to arrive from the proxy’s address. Add the proxy’s IP and restart:
Use 127.0.0.1 for a proxy on the same host, or the proxy’s own IP if it’s on another machine.
The API isn’t ready yet. Check the container status and logs:
The api healthcheck probes /readyz from inside the container, which is the only place it answers. From outside, /api/readyz is deliberately 404 so a stranger can’t learn whether the database is up, and /api/healthz only says the process is alive.
Run journalctl -u caddy to see the full error.
  • DNS-01 challenge: verify the Cloudflare API token has both Zone → DNS → Edit and Zone → Zone → Read permissions on the correct zone. Missing Zone → Zone → Read causes an “unknown error” when the module tries to look up the zone ID.
  • HTTP challenge: make sure ports 80 and 443 are reachable from the internet under your domain name, and that the domain resolves to this host.
The Docker stack isn’t running, or WEB_BIND isn’t 127.0.0.1. Check the stack status and test the connection locally:

​
Still stuck?

Check the GitHub Issues page — someone may have hit the same problem. If not, open a new issue with your error output and the relevant parts of your .env (redact any passwords or secrets).