Troubleshooting

The installer shows a red check

Each line names what is missing: a PHP version, an extension or a folder that isn't writable. Ask your host to enable the extension, or switch PHP version in your control panel. Make storage/ , bootstrap/cache/  and .env  writable by PHP.

Every page returns 404 or 500

Check that the document root points at public/ , or that the root .htaccess  was uploaded (dotfiles are often hidden or skipped by FTP clients). mod_rewrite  must be enabled.

The dashboard never opens after adding the snippet

It waits for the first pageview. Check, in order:

  • The script URL loads in your browser.
  • data-domain  matches the site you added. A leading www.  is ignored.
  • You aren't testing from localhost . Use the local  variant for that.
  • A shield isn't blocking your own IP, country or page.
  • You aren't blocking the script with an ad blocker. A proxy helps.

In your browser's network tab, POST /api/event  should return 202 . A 404  means Tidemark doesn't know the domain. A 400  means the payload was missing a name, URL or domain.

My own visits don't show

Tidemark ignores known bots and, by default, localhost . Set TIDEMARK_IGNORE_IP  or add an IP shield to exclude yourself on purpose, or remove it to include yourself.

Locations are empty

Country, region and city need geolocation. Behind Cloudflare, Vercel or CloudFront it works with no setup. Otherwise install a GeoLite2 City database. See Configuration.

Behind a proxy or CDN the IP looks wrong

Tidemark reads the client IP from CF-Connecting-IP , X-Client-IP , X-Forwarded-For , X-Real-IP , X-Appengine-User-Ip  and True-Client-IP , in that order.

The update check says it can't reach GitHub

Your host may block outgoing connections. Download the release zip yourself and upload it on the same page.

The in-app update fails

Check that the zip  extension is loaded and that PHP can write to the project folder. Otherwise update over FTP. If the files were replaced but the dashboard misbehaves afterwards, reload once: the migrations run on the first request after an update.