Troubleshooting
The installer shows a red check
Section titled “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
Section titled “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
Section titled “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-domainmatches the site you added. A leadingwww.is ignored.- You aren’t testing from
localhost. Use thelocalvariant 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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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.