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 Docker server container is running and that UPTIME_APP_API_BASE_URL is correctly set.

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: Update the API URL in your docker-compose.yml to use your host machine's IP address:

UPTIME_APP_API_BASE_URL: "http://[host-ip]:5000/api/v1"

Replace [host-ip] with your server's actual IP address (e.g. 192.168.1.100).

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