Umami Not Working? Common Errors & Fixes

If Umami shows no visits, the script is usually missing or blocked, data-domains doesn't match your exact hostname, or a proxy breaks the /api/send request with CORS errors or redirects. Check the page source and the Network tab for a 200 response from /api/send.

Filter lists block umami.is and the default script.js and /api/send paths. Rename them with TRACKER_SCRIPT_NAME and COLLECT_API_ENDPOINT when self-hosting, or proxy the script and endpoint through your own domain for Umami Cloud.

Umami v3 runs on PostgreSQL only. To upgrade a MySQL instance, first update to v2.19.0, migrate the data into PostgreSQL with a dump or CSV export, then upgrade to v3.

When an upgrade migration fails, Prisma marks it failed (P3018) and blocks every later one (P3009), so the build stops at check-db. Restore free disk space, mark the failed migration rolled back, and rerun it; on big tables run the heavy update in batches.

The check-db step can't reach PostgreSQL. Usually DATABASE_URL points at the wrong host (it must be the Compose service name, not localhost), Postgres isn't ready yet, or a required variable like APP_SECRET is missing.

The default self-hosted login is admin / umami. If you changed it and forgot it, reset it from the server with the bundled change-password script or by resetting the password hash in the database.

Self-hosted Umami reads location from proxy headers or the visitor IP. If a proxy hides the real IP or sends only country headers, everyone shows as Unknown or as your server's country. Forward the real IP and Cloudflare location headers, or set SKIP_LOCATION_HEADERS.

Umami records events from data-umami-event attributes or umami.track() calls, and they appear on the website's Events page, not the main overview. Check the event name (max 50 characters), that the element is actually clicked, and that a request fires to /api/send.

Run localStorage.setItem('umami.disabled', 1) in the browser console on each of your sites. Self-hosters can also ignore their IPs with IGNORE_IP, and you can stop localhost tracking with data-domains.

On self-hosted PostgreSQL, Umami computes charts from raw events, so long date ranges on big sites can time out or run out of memory. Add database resources and indexes, tune connection pooling, or move high-volume sites to ClickHouse or Umami Cloud. If errors are intermittent, check uBlock Origin on the Umami domain.

Umami counts a visit with only one event as a bounce and measures time only between events, so readers who stay on one page and leave show 0 seconds. Send an extra engagement event (scroll or timer) to get realistic numbers.

Go to Settings > Billing > Manage plan in Umami Cloud to open the Stripe billing portal and cancel. Cancelling within the 14-day trial is free; otherwise the change takes effect at the next billing cycle.