Skip to content

Troubleshooting ​

Most problems show up on Administration › System › Service status with a sentence saying what to do, and in storage/logs/laravel.log. Start there; this page lists the usual causes and their fixes.

Look up what you needSite owners, DevOpsSingle user · SaaS

First steps ​

  1. Open Administration › System and click Check now under Service status.
  2. Run the checks on the server: php artisan replora:health and php artisan replora:doctor --single-server.
  3. Read the end of the log: tail -n 100 storage/logs/laravel.log.

Never leave APP_DEBUG on

APP_DEBUG=true shows error details in the browser, including configuration values. If you turn it on to see an error, turn it off again right after (php artisan config:clear if you cache configuration).

Installer problems ​

ProblemCause and fix
Blank page or 500 before the installer opensPHP can't write storage/ or bootstrap/cache/, or a required extension is missing. Fix permissions (see below) and check the web server's PHP error log
An item marked ✕ on the server checkEach item says how to fix it; see Server requirements. Click Check again after fixing
Open this installer at the site’s own address and use that address here (this page was opened at …).You opened the installer at another address (an IP, a temporary URL). Open it at the real address. The license is attached to that domain
Purchase code messagesSee Your purchase code
Could not connect to the database: …Wrong host, port, name, user or password, or PostgreSQL doesn't accept the connection (check pg_hba.conf and listen_addresses for remote databases). The rest of the message is PostgreSQL's reason
The database tables could not be created: …The user can connect but not create tables. Make it the database's owner (ALTER DATABASE replora OWNER TO replora;)
An account exists already. Sign in instead.The database isn't empty. Use an empty database, or sign in
The installer is still working on this step. Wait a moment, then reload the page.A double click or second tab. Wait and reload
Too many attempts in a short time.The installer's rate limit. Wait the seconds shown
This copy needs a purchase code: use --purchase-code=…--skip-license only works with bundled builds
Replora is already installed.replora:install refuses on an installed site

Error pages ​

What you seeCause and fix
503 Service Unavailable (maintenance page)Maintenance mode is on: turned on from the System page, or left on by an interrupted replora:upgrade. Administrators can still sign in and turn it off under System › Maintenance mode; on the server run php artisan up
Replora is not installed yet. Open /install in a browser. (JSON, 503)The API answers this until installation is finished
404 on every pageYou opened the site at a host name other than the one in APP_URL (for example the server's IP). Replora only answers on its own host and its subdomains. Use the address in APP_URL, or change APP_URL
404 on /installNormal once installed: the installer closes itself
500 Server ErrorRead storage/logs/laravel.log. Usual causes: storage/ not writable, a missing PHP extension after a PHP upgrade, wrong database settings in .env
419 Page Expired or signed out right after signing inThe address in the browser differs from APP_URL (http vs https, www., another port), so the session cookie and sign-in don't match. Set APP_URL and SANCTUM_STATEFUL_DOMAINS to the exact address, then php artisan config:clear
429 Too Many RequestsA rate limit. For tracker requests raise RECORDINGS_INGEST_PER_MINUTE when many visitors share one IP address

Recordings don't appear ​

Work through this list in order:

  1. Is the snippet on the page? Open the website, view the page source and look for <script async src="https://analytics.example.com/t.js" data-site="…">. Tag managers and caching plugins can drop or delay it.
  2. Does t.js load? In the browser's developer tools, Network tab, reload: t.js must answer 200. The Tracking script check on the System page tests the same (… doesn’t serve the script (404): recordings stop.). A 404 usually means an Nginx rule answers .js files from disk; see VPS.
  3. Mixed content: a website on https:// can't load the script from an http:// Replora. Turn on HTTPS for Replora.
  4. Content Security Policy: if the website sends a Content-Security-Policy header, add your Replora address to script-src and connect-src. The browser console shows Refused to load… or Refused to connect… otherwise.
  5. Look at the uploads (/i/<key> requests in the Network tab):
AnswerMeaningFix
204Accepted (or dropped on purpose by the website's recording rules: excluded IP addresses, sampling, pages; the answer then carries an X-SR-Control header)If sessions still don't appear, see step 6. Check the website's recording rules
403The page's domain isn't in the website's allowed domainsAdd the domain (subdomains of an allowed domain are accepted too) in the website's settings
404Unknown website key, or recording is paused for the websiteCopy the snippet again; resume recording in the website's settings
413 / 400A batch too large (more than 5 MB compressed) or brokenRare; send the page address to support
429Rate limit per IP addressRaise RECORDINGS_INGEST_PER_MINUTE
blocked / (failed)An ad or privacy blocker in your own browserTest in a private window without extensions
  1. Is a worker running? Batches wait in the queue until a worker processes them. Background jobs must say Workers keep up; … jobs are waiting, the oldest for … minutes: is a queue worker running? means it isn't. See Background worker.
  2. Plan limits (SaaS): when an account has used its Sessions per month, new sessions aren't counted until the next month; beyond Session replays per month sessions are counted without a replay. The account's plan page shows the usage.
  3. Recordings arriving on the System page says when the last recording arrived (Nothing arrived for 2 days: is the tracking code still on your websites?, shown when nothing came in for a day).

Replays look broken or unstyled ​

  • Stylesheets are fetched again at replay time when no copy was kept. Keep RECORDINGS_CACHE_STYLESHEETS=true (the default) so copies are kept on the server.
  • Stylesheets on an intranet or localhost are only fetched with RECORDINGS_STYLESHEETS_ALLOW_PRIVATE=true (default: only in the Single user edition), and only from hosts in the website's allowed domains.
  • Fonts and images are loaded from the recorded website during replay. If that website refuses other origins for fonts, text falls back to another font.
  • Elements masked or left out by the website's privacy settings are shown as blocks on purpose.

Background jobs and cron ​

ProblemFix
Scheduled tasks have never run… / Last ran … minutes ago…Add or fix the cron line; test it with sudo -u www-data php artisan schedule:run. See Scheduler
Jobs wait, the worker is "running"The worker runs old code or settings: php artisan queue:restart. Check storage/logs/worker.log
… jobs failed in the last 24 hoursphp artisan queue:failed shows the error of each; fix it and php artisan queue:retry all
Worker killed on shared hostingUse the cron worker with --stop-when-empty --max-time=55, or QUEUE_CONNECTION=sync. See Shared hosting

Email ​

Message (Email delivery check)Fix
Emails are only written to the log, not sent: set up email delivery in Settings › Installation.Choose a sending method in Settings › Installation › Email delivery
The mail server host:port can’t be reached: …Wrong host or port, or outgoing SMTP ports blocked by the host. Many hosts block port 25: use 587 or 465
The mail server host:port answered unexpectedly.The port doesn't speak SMTP, or SSL/STARTTLS is mixed up: port 465 needs SSL/TLS from the start

Emails sent but not received: check the sender domain's SPF and DKIM records, and the From address. See Email delivery.

File permissions ​

The web server user (www-data on Ubuntu and Debian, often your account user on shared hosting) must own the application folder, or at least be able to write to storage/, bootstrap/cache/, .env, modules/ and, for one-click updates, the application folder itself:

bash
cd /var/www/replora
sudo chown -R www-data:www-data .
sudo find . -type d -exec chmod 775 {} \;
sudo find . -type f -exec chmod 664 {} \;
sudo chmod 640 .env
sudo chmod +x artisan

Run artisan commands as that user (sudo -u www-data php artisan …). Commands run as root create files the web server can't change later (log files, caches, downloaded modules).

Locked out ​

ProblemFix
Lost the only administrator's password and email doesn't workphp artisan replora:admin [email protected] --name="Your Name" creates a new administrator
A wrong reCAPTCHA key keeps everyone from signing inphp artisan replora:recaptcha off
Installer opens on a site that was installedstorage/app/replora-installed.json is missing and the database can't be reached (with a reachable database that has accounts, the marker is written again by itself). Fix the database settings in .env, or restore storage/

Every service check ​

The checks on System › Service status (also php artisan replora:health, which runs every five minutes and emails administrators when a check starts failing or recovers):

CheckWorkingNeeds attention / Failing
DatabaseConnected (pgsql).The connection error
CacheReads and writes work (file).A value written to the cache could not be read back.
Background jobsWorkers keep up (database). · Jobs run at once, in the request (no worker needed).… jobs failed in the last 24 hours… · … jobs are waiting, the oldest for … minutes: is a queue worker running?
Scheduled tasksRan … seconds ago.Scheduled tasks have never run… · Last ran … minutes ago…
StorageFiles are written and read; … free of ….Disk almost full: …. (under 10 % or 1 GB free) · Files can’t be written to the “local” / “recordings” disk.
Email deliverySent through …. · The mail server … answers.Emails are only written to the log… · … can’t be reached… · … answered unexpectedly.
Websitehttps://… answers (200).https://… answers with an error (…). (Not checked on php artisan serve)
Tracking scriptWebsites can load it from https://…/t.js.… doesn’t serve the script (…): recordings stop. (Not checked on php artisan serve)
SSL certificateValid for … more days.The certificate expires in … days. (under 14) · The certificate expired … days ago. · The certificate of … couldn’t be read. · The site runs without https… (Not checked for http on localhost)
License and modulesPurchase code saved (…), support until ….Missing modules: …. · Some modules belong to another version… · No purchase code is saved… · Support ended on …: updates keep working…
Maintenance modeOff: the website and dashboard are open.On: visitors see the maintenance page. Recording and webhooks keep working.
Recordings arrivingThe last one arrived … ago.No recording has arrived yet: check that the tracking code is on your websites. · Nothing arrived for …: is the tracking code still on your websites? (Not checked without websites)

Still stuck? ​

Collect the System page's messages, the output of php artisan replora:doctor, the last lines of storage/logs/laravel.log, your Replora and PHP versions, and contact support with your purchase code.

Replora: see what your visitors see.