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.

Made with Pepper 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 a fresh installation, confirm that the server runs MySQL 8.4, or MariaDB 10.11, 11.4 or 11.8, and verify:

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

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

The installer names the reason when the check fails, and writes it to storage/logs/laravel.log without the password. Each message and its fix is in Database check messages.

The fresh installer does not accept other MySQL versions, MariaDB 10.6 and earlier, MariaDB short-term releases, or a database that already contains unrelated tables. Create a new empty database on a supported server instead of removing tables through the installer. The installer does not upgrade an existing Made with Pepper installation. It refuses its database before any migration and changes nothing. Follow Updates for an existing installation; the package must support your installed version as a starting point. See the changelog for upgrade notes.

The server must support the InnoDB storage engine. Made with Pepper creates all tables as InnoDB tables, also when the server uses MyISAM as its default engine.

If installation fails during database setup, find the support reference from the message in storage/logs/laravel.log. The log entry shows the database error code and message. If the message says that installation stopped while it created the database tables, follow Failure recovery. Remove partial tables only from the new, empty installation target that this failed attempt created. Never remove existing business data. See Failure recovery.

Links or styles break in a subfolder

Made with Pepper does not run in a subfolder such as example.com/invoices. Links, signed quote links, cookies and assets can break there. Move the installation to a domain or subdomain, for example invoices.example.com, and point its document root at the public/ directory.

Pages show unstyled content

If a 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/

Emails fail after choosing SMTP

If storage/logs/laravel.log shows UnsupportedSchemeException or a mailer scheme error, open .env and set MAIL_SCHEME=smtp for port 587 or MAIL_SCHEME=smtps for port 465. The mailer does not accept the values tls and ssl.

An email stays queued or shows an unknown result

Open the document and read its Delivery tab.

• Email queued for a long time: the cron job does not run. The page says "The scheduler has not run since {time}. Check the cron job." Check the cron entry, then look at Settings > Email for the time of the last run.
• Email failed: read the reason. Fix the recipient address or the mail settings, then click Send again.
• Email result unknown: Made with Pepper does not know if the email left the mail server. Check the sent log of your mail provider. Click Send again only if the email is not there.
• Not emailed after you sent: the mail setting writes emails to the log file. Set MAIL_MAILER to smtp or resend in .env.

See Retries and results.

The issued original is missing or changed

The document page says "The issued original (PDF) is missing or changed. Restore it from a backup." Made with Pepper found no file, or a file that does not match its SHA-256. Recover a complete database and media snapshot in a separate installation. Until then, Download regenerated copy gives a copy marked "Regenerated copy. The issued original is not available." Made with Pepper does not email that copy.

Wrong timezone

Check Business timezone in Settings > Company first. It controls business dates and scheduled document work. The installer also writes APP_TIMEZONE for the server default.

Unexpected logout or session expiry

Made with Pepper 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 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.

Error pages

Every error page says what happened and offers one next action. The pages work without the database and without the compiled assets, so they still show when the server has a problem. A page for a missing record uses the language of the person who opens it.

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 Issued or Partially paid (not Draft or Paid)
• Someone emailed the invoice, or recorded a delivery. An invoice that shows Not emailed gets no automatic reminders
• The customer has a contact with Receives reminders, or an email address. The invoice page says "No reminder recipient" when nobody can receive a reminder
• The invoice has not reached the reminder cap (default: 5 automatic reminders 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 queue the automatic reminders from the command line:

php artisan reminders:send

Backup or restore fails

Backup creation fails

• Check that the PHP account can write to storage/backups/ and storage/framework/.
• Check that proc_open() and mysqldump are available to PHP. mariadb-dump also works.
• Check free disk space and the archive limits.
• Check that the account can read its database and both media directories.

A failed dump, timeout or failed write stops creation. Incomplete files do not appear as completed backups. Messages omit database credentials and raw client diagnostics.

Restore fails

Recovery runs from the shell in a separate installation. The browser cannot overwrite an existing database.

Recovery requires proc_open() and mysql, or mariadb. Follow the complete procedure, including key preservation and verification.

The snapshot omits newer records

Keep the source intact. Stop all writers and take a new final snapshot before a planned cutover.

For disaster recovery, reconcile missing invoices and payments before activation. After the replacement receives writes, never switch back to the stale source.

An update does not install

Updates lists every check with its result. Fix the red check, then click Check package again.

Still stuck

See Getting support and include the relevant log lines, Made with Pepper version, PHP version, database type, and exact steps to reproduce.

A permitted page is missing

Check enabled modules, the account role and any guest scope. A permission does not enable a disabled module. A guest scope can hide records without changing their existence. Ask the owner to review Product areas and access.