Common Issues

Start with the error message in storage/logs/laravel.log or your hosting error log.

Blank page or 500 error

Check:

• PHP 8.4+ is active for the site
• Required PHP extensions are enabled
• storage/ and bootstrap/cache/ are writable
• .env exists after setup
• vendor/ exists in the uploaded files
• public/build/manifest.json exists in the uploaded files
• Your web server points to public/

The specific error is usually in storage/logs/laravel.log or your hosting error log.

Do not fix a normal buyer install by running Composer, npm, Vite, or Node.js commands. The release package should already include vendor/ and public/build/. If those folders are missing, re-upload the complete release package.

InvoiceScript does not load runtime assets from CDNs. Missing styles or scripts usually mean public/build/ was not uploaded correctly.

A directory is not writable

Make these directories writable by the web server:

• storage/
• bootstrap/cache/

On most shared hosts, permissions of 755 or 775 work. Some hosts require changing the file owner through the control panel.

Database connection fails

For SQLite, make sure the database directory is writable.

For MySQL/MariaDB, verify:

• Host
• Port
• Database name
• Username
• Password
• User permissions

Some hosts use localhost; others require a hostname from the hosting panel.

Bootstrap page shows unstyled content

If the bootstrap verification page loads without styles:

• Verify public/build/manifest.json exists
• Verify public/build/assets/ contains CSS and JS files
• Check that your web server serves static files from public/

Wrong timezone

Check the APP_TIMEZONE value in .env. The default is Europe/Amsterdam. Use any valid PHP timezone identifier.

Unexpected logout or session expiry

InvoiceScript logs you out after 30 minutes of inactivity by default — unless you check Remember me when logging in. Remembered sessions bypass the idle timeout.

If you are not using "Remember me" and the timeout is too short, increase it in .env:

SESSION_IDLE_TIMEOUT=60

Set to 0 to disable the idle timeout entirely for all sessions.

See Security > Troubleshooting sessions for full details, including shared hosting considerations and the interaction between "Remember me", idle timeout, and session lifetime.

403 Forbidden on a page

If a team member gets a 403 error on a page, their role does not allow access to that area.

Check the user's role in Settings > Users. See Roles and Permissions for the full matrix.

Recurring invoices not generating

Recurring invoices require a cron job. Check:

• A cron entry runs php artisan schedule:run every minute
• The schedule is Active (not paused or completed)
• The schedule's next invoice date is today or in the past
• The server timezone matches APP_TIMEZONE in .env

You can generate manually from the command line:

php artisan recurring:generate

See CLI Commands for cron setup instructions.

Reminders not sending

Automatic reminders require cron, a working email configuration, and the reminders toggle. Check:

• A cron entry runs php artisan schedule:run every minute
• Settings > Reminders has reminders enabled
• The invoice status is Sent or Partially paid (not Draft or Paid)
• The invoice has not reached the reminder cap (default: 5 per invoice)
• Email delivery is configured correctly (SMTP or Resend API in .env)
• The customer has not disabled reminders via a per-customer override

You can send reminders manually from the command line:

php artisan reminders:send

Backup or restore fails

Backup creation fails

• Verify storage/backups/ is writable by the web server (permissions 755 or 775)
• For MySQL, verify the mysqldump command is available on the server. Some shared hosts do not include it in the PHP execution path. Contact your host if needed.
• Check storage/logs/laravel.log for the specific error message

Restore fails

• If the backup was encrypted, make sure you entered the correct passphrase
• If you see "Invalid backup: missing manifest.json", the file is not a valid InvoiceScript backup
• If you see "Failed to open backup archive", the ZIP file may be corrupted — try downloading a fresh copy
• After a restore, you are logged out and must sign in again. This is expected behavior.

Backups are empty or too small

• Verify the database file exists and is not zero bytes
• Check that storage/app/private/ and storage/app/public/ are readable by the web server

Still stuck

See Getting Support and include the relevant log lines, InvoiceScript version, PHP version, database type, and exact steps to reproduce.