Common Issues

Quick fixes for the most frequently reported issues.

Blank page or 500 error after installation

Check that PHP 8.3+ is active and the required extensions are installed. Check your hosting error log for specific PHP errors.

Common causes:

• PHP version below 8.3
• Missing pdo_mysql extension
• .env file not writable during installation
• storage/logs/ directory not writable

Root URL returns 403

Make sure the .htaccess file is present in your installation root and that Apache's mod_rewrite is enabled. The .htaccess rewrites all requests into public/. If it's missing or AllowOverride is set to None, Apache cannot process the rewrite rules.

Permission errors

Make sure storage/logs/ and public/uploads/ are writable by the web server. On most hosts, permissions of 755 or 775 work. The installation wizard checks these in Step 1.

Missing CSS or JS after update

Clear your browser cache (Ctrl+Shift+R or Cmd+Shift+R) and reload. VoxelBooking's compiled assets include version hashes, but aggressive browser or CDN caching can serve stale files.

Email not sending

VoxelBooking uses the mail transport configured in Admin > Settings > Email. If confirmation emails are not arriving:

1. Verify your selected transport and credentials in Admin > Settings > Email
2. Use the Send Test Email button to confirm delivery
3. If you use SMTP, check that your hosting provider allows outbound SMTP connections (some hosts block ports 465 and 587)
4. If SMTP ports are blocked, switch to Resend to send via HTTPS over port 443
5. Check the spam folder - the first email from a new domain often lands there

Pages show the homepage on Nginx

Symptoms: The homepage works, but visiting /features or /pricing returns the homepage content instead of the correct page.

Cause: VoxelBooking ships .htaccess for Apache clean URL routing. Nginx ignores .htaccess and its default try_files rule falls back to index.php when it cannot find the file.

Fix: Add a rewrite rule to your Nginx config:

location / {
    try_files $uri $uri/ /public/index.php?$query_string;
}

Upload too large

If the in-admin updater rejects your update zip, your hosting's PHP upload limit is too low. Either increase upload_max_filesize in your PHP config, or use the FTP upload method described in Updating.

Timezone is wrong on bookings

VoxelBooking uses the timezone set in Admin > Settings > General. Make sure this matches your business location. Each business inherits the system timezone. If bookings appear at the wrong time, check this setting first.

Agent API returns 401 on Nginx

Symptoms: Agent API requests return a "Missing Authorization header" error even with a valid API key.

Cause: Nginx strips the Authorization header before forwarding requests to PHP-FPM.

Fix: Add this line inside your location ~ \.php$ block:

fastcgi_param HTTP_AUTHORIZATION $http_authorization;

This tells Nginx to pass the Authorization header to PHP.

White screen after update

Clear your browser cache and reload. If the issue persists, check your hosting error log for PHP errors. Make sure all files were uploaded correctly during the update - see Updating for the complete process.