FAQ and troubleshooting

HTTP 500 immediately after install

  • Check storage/ and bootstrap/cache/ are writable by the web user.
  • Confirm APP_KEY is set (installer sets this; or run php artisan key:generate).
  • Set APP_DEBUG=false in production and read storage/logs/laravel.log.

Admin or tenant panel is blank / unstyled

Published Filament assets may be missing. From SSH or cPanel Terminal:

php artisan filament:assets
php artisan config:clear

Hard-refresh the browser.

Cron not running

  • Verify the crontab line uses the full path to php and artisan.
  • Wait two minutes and check Admin → Diagnostics → Cron / Scheduler heartbeat.
  • See Cron and queue.

Emails not sending

  • Admin → Settings → Email — run Send test email.
  • Confirm SMTP host, port, TLS, username, and password.
  • Check spam folders and that the From domain has valid DNS (SPF/DKIM as required by your host).

Licence / install lock

  • /install is blocked after success by storage/installed.lock. The installer remains in the application code, so there is no install folder to delete.
  • For a new installation, keep a backup of the current site, extract a fresh package into a new folder, and use a new empty database. Point the local domain at the new folder's public/ directory and open /install there. Do not remove the lock on a site that contains customer data.

Demo data reset

php artisan demo:reset runs only when DEMO_MODE=true. It resets the canonical demo tenant and removes businesses created through signup on demo servers. Do not run it on a production install with DEMO_MODE disabled — the command exits with an error.

CAPTCHA (Cloudflare Turnstile)

The public booking page uses Cloudflare Turnstile by default to prevent spam bookings. To enable:

  1. Create a Turnstile site in the Cloudflare Dashboard → Security → Turnstile.
  2. Add to .env:
CAPTCHA_PROVIDER=turnstile
TURNSTILE_SITE_KEY=0x4AAAAAAAxxxxxxxxxxxxxxxxxxxxxxx
TURNSTILE_SECRET_KEY=0x4AAAAAAAxxxxxxxxxxxxxxxxxxxxxxx

To disable CAPTCHA (development/demo only — not recommended for production):

CAPTCHA_PROVIDER=null

The honeypot and minimum-fill-time bot guards remain active even when CAPTCHA is disabled.

Diagnostics probe reference

Open Admin → Diagnostics to see real-time health for all config knobs.

Probe What it checks FAIL remediation
PHP version & extensions PHP ≥ 8.3 + required extensions Upgrade PHP; install missing extensions
PHP timezone / DST tables Bundled tz DB handles DST correctly php -r "echo timezone_version_get();" — install a newer php-tzdata package
Daylight saving time (booking times) Booking engine handles DST gaps and overlaps Fix tz DB (see above); reload Diagnostics to re-sync
Cron / Scheduler heartbeat Cron fires at least every 2 min Add/fix the schedule:run cron entry (shared hosting install — cron step)
Queue worker liveness Queue worker processed a job in the last 10 min The same cron entry drives the worker — add/fix schedule:run. On VPS: check Supervisor/Horizon
Queue connection Not sync Set QUEUE_CONNECTION=database in .env
Rate-limiter cache store Not file Set CACHE_STORE=database in .env
Client-IP resolution Real visitor IP is resolved Set CLIENT_IP_MODE correctly (see Rate limiter IP resolution)
SMTP relay Relay accepts test send; From-domain aligned Fix MAIL_HOST/MAIL_PORT/MAIL_USERNAME/MAIL_PASSWORD; check DMARC alignment
A2P SMS sender Twilio credentials set and healthy Set TWILIO_* vars; rotate if 401/403 flagged
Payment gateway configuration Migrations present; at least one tenant gateway active Run php artisan migrate; tenant adds gateway in Settings
Payment reconcile sweep health No stalled pending/authorized payments Check cron is running; verify QUEUE_CONNECTION≠sync
Slot availability Booking engine computes slots correctly Should always pass; if not, check DST/tz probes first
Analytics catalog seed Analytics tables seeded Run php artisan migrate --force
Analytics compiler Query compiler is functional Should always pass; contact support
appointment_facts view HIPAA boundary view present Run php artisan migrate --force
AI-narrative catalog health No PII in AI-visible columns; model ID pinned See AI narrative
External calendar sync Conflict-checking stays internal; connected calendars are a publish feed Always a warning on a stock install. Staff enter personal commitments as schedule blocks. This warning does not block install
Google Calendar push OAuth client, revoked grants, and outbound HTTPS to Google OK when no client id is saved. WARN when the secret is missing, a grant was revoked, or a Microsoft row is stored. FAIL when an active Google connection cannot reach www.googleapis.com

Probe colours:

  • 🟢 OK — everything is correct.
  • 🟡 WARN — not a blocker, but worth fixing (e.g. SMS not configured yet).
  • 🔴 FAIL — must be fixed; bookings, payments, or security may be broken.