General troubleshooting steps

If you're experiencing issues with Checkmate, work through these checks:

Verify ports — ensure the port used by Checkmate (default 52345) is not occupied by another service
Check environment variables — confirm database connections and API URLs point to the correct addresses
Test connectivity — access the server endpoint directly at http://localhost:52345/api/v1
Check Docker containers — verify all containers are running with docker ps
Inspect logs — check container logs with docker logs <container_name>
Clear browser cache — clear cache and cookies, then reload

Common issues

Registration page not appearing

Symptom: After starting Checkmate, you're not redirected to the registration page.

Cause: The client cannot reach the server.

Fix: Verify the Checkmate container is running (docker ps). On the current single image the client is served by the API server itself, so there is no separate API URL to configure — but if you've overridden CLIENT_CONFIG_API_BASE_URL, check that it points at a reachable address.

Promise errors or monitors stuck in pending

Symptom: JavaScript promise errors in the console, or monitors never complete their first check.

Possible causes:

AdBlocker conflict — AdBlocker Ultimate (and similar extensions) can interfere with Checkmate. Disable ad blockers or whitelist Checkmate's URL.
Docker socket proxy — when using Docker container monitoring with local volumes, a Docker socket proxy may be required.

Cannot access Checkmate from another machine

Symptom: Checkmate works on localhost but not from other devices on the network.

Fix: With the current single image the client calls the API on whatever origin it's served from, so browsing http://[host-ip]:52345 from another machine works without configuration. If it doesn't:

Set CLIENT_HOST in your docker-compose.yml to the address other machines use, e.g. http://192.168.1.100:52345.
If you've set CLIENT_CONFIG_API_BASE_URL, make sure it uses the host's IP, not localhost.

On images older than v3.10.0, the equivalent setting was UPTIME_APP_API_BASE_URL — that variable is no longer read; see the installation guide for the migration.

Docker socket permission errors

Symptom: Docker monitoring fails with permission errors related to /var/run/docker.sock.

Fix:

Verify Docker group membership and GID on the host
Configure proper user permissions in the compose file
Ensure the socket is mounted as read-only:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Token expiry issues

Symptom: Users are logged out too frequently.

Fix: Adjust the TOKEN_TTL environment variable in your server .env file. The format follows the ms library syntax:

TOKEN_TTL="99d"    # 99 days
TOKEN_TTL="24h"    # 24 hours
TOKEN_TTL="7d"     # 7 days

PageSpeed monitoring not working

Symptom: PageSpeed checks fail or return no data.

Fix: PageSpeed monitoring requires a Google PageSpeed API key. Add it in Settings or set it as an environment variable. You can get a free key from the Google PageSpeed API.

Getting help

If your issue isn't covered here:

Discord community — fastest way to get help
GitHub Discussions — for longer-form questions
GitHub Issues — for bug reports

Troubleshooting