Appearance
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.
First steps
- Open Administration › System and click Check now under Service status.
- Run the checks on the server:
php artisan replora:healthandphp artisan replora:doctor --single-server. - 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
| Problem | Cause and fix |
|---|---|
| Blank page or 500 before the installer opens | PHP 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 check | Each 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 messages | See 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 see | Cause 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 page | You 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 /install | Normal once installed: the installer closes itself |
| 500 Server Error | Read 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 in | The 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 Requests | A 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:
- 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. - Does
t.jsload? In the browser's developer tools, Network tab, reload:t.jsmust 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.jsfiles from disk; see VPS. - Mixed content: a website on
https://can't load the script from anhttp://Replora. Turn on HTTPS for Replora. - Content Security Policy: if the website sends a
Content-Security-Policyheader, add your Replora address toscript-srcandconnect-src. The browser console shows Refused to load… or Refused to connect… otherwise. - Look at the uploads (
/i/<key>requests in the Network tab):
| Answer | Meaning | Fix |
|---|---|---|
| 204 | Accepted (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 |
| 403 | The page's domain isn't in the website's allowed domains | Add the domain (subdomains of an allowed domain are accepted too) in the website's settings |
| 404 | Unknown website key, or recording is paused for the website | Copy the snippet again; resume recording in the website's settings |
| 413 / 400 | A batch too large (more than 5 MB compressed) or broken | Rare; send the page address to support |
| 429 | Rate limit per IP address | Raise RECORDINGS_INGEST_PER_MINUTE |
| blocked / (failed) | An ad or privacy blocker in your own browser | Test in a private window without extensions |
- 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.
- 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.
- 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
localhostare only fetched withRECORDINGS_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
| Problem | Fix |
|---|---|
| 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 hours | php artisan queue:failed shows the error of each; fix it and php artisan queue:retry all |
| Worker killed on shared hosting | Use 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 artisanRun 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
| Problem | Fix |
|---|---|
| Lost the only administrator's password and email doesn't work | php artisan replora:admin [email protected] --name="Your Name" creates a new administrator |
| A wrong reCAPTCHA key keeps everyone from signing in | php artisan replora:recaptcha off |
| Installer opens on a site that was installed | storage/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):
| Check | Working | Needs attention / Failing |
|---|---|---|
| Database | Connected (pgsql). | The connection error |
| Cache | Reads and writes work (file). | A value written to the cache could not be read back. |
| Background jobs | Workers 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 tasks | Ran … seconds ago. | Scheduled tasks have never run… · Last ran … minutes ago… |
| Storage | Files 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 delivery | Sent through …. · The mail server … answers. | Emails are only written to the log… · … can’t be reached… · … answered unexpectedly. |
| Website | https://… answers (200). | https://… answers with an error (…). (Not checked on php artisan serve) |
| Tracking script | Websites can load it from https://…/t.js. | … doesn’t serve the script (…): recordings stop. (Not checked on php artisan serve) |
| SSL certificate | Valid 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 modules | Purchase code saved (…), support until …. | Missing modules: …. · Some modules belong to another version… · No purchase code is saved… · Support ended on …: updates keep working… |
| Maintenance mode | Off: the website and dashboard are open. | On: visitors see the maintenance page. Recording and webhooks keep working. |
| Recordings arriving | The 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.
