Troubleshooting

Fixes for installer checks, cron that does not run, missing email, IMAP errors, permissions and lockouts.

This article lists problems that come up when installing and running Tidemark Billing, with the cause and the fix for each.

The installer shows a cross next to a check#

The /install page lists each requirement. Hover over a failed one to see its hint. The checks and their fixes:

Check	Fix
PHP 8.3 or newer	Upgrade PHP in your hosting control panel
PHP extension (mbstring, openssl, pdo, fileinfo, ctype, tokenizer, xml, curl, json, bcmath)	Enable the extension
A database driver	Enable `pdo_sqlite`, `pdo_mysql` or `pdo_pgsql`
Writable `storage/` or `bootstrap/cache/`	Make the folder writable by the web server (`chmod 775`)
Writable `.env`	Make `.env` writable, or configure it by hand

The install form only appears once every check passes. Reload the page after fixing them.

"Could not connect to the database"#

The installer tried your database details and the connection failed. The message after the colon is the error from the database. Check the host, port, database name and username. For SQLite, make sure database/ is writable.

Every page redirects to /install#

Until the file storage/app/installed exists, all pages redirect to the installer. If you have installed already, the file is missing, usually because the storage/ folder was replaced or not copied during a move or update. Restore your storage/ folder. Do not run the installer again over an existing database unless you mean to: it runs the migrations and creates or updates the admin account for the email you enter.

/install sends me to the home page#

That is expected after a successful install. The installer closes itself once storage/app/installed exists.

Invoices and reminders are not being created#

The scheduler is probably not running.

Open Settings → System and copy the cron line or the web cron URL.
Check that your cron job exists and runs every minute. See Set up the cron job.
If you use the web cron URL, a 404 means the token is wrong. Regenerate URL invalidates the old one, so update your job after regenerating.
Select Run billing tasks now. If this works but invoices still do not appear on their own, the cron entry is the problem.

The billing run itself happens once a day at 02:30 UTC, so a new setting may not show an effect until then.

Customers get no email#

A fresh install uses MAIL_MAILER=log, which only writes to the log. Set Method to SMTP under Settings → Email.
Check that Send emails is ticked.
Select Send test email. It uses the saved settings, and shows the mail server's error if sending fails.

See Email.

Support email is not arriving (IMAP)#

Open the department under Departments. If the last check failed, the form shows "The last check failed" and the server's message. Use Test connection, which tests the values currently typed in the form and tells you the user, server and encryption it tried (never the password).

Since version 0.3.1, sign-in uses SASL PLAIN first, then LOGIN, as mail clients do. A failed sign-in lists what the server said to each method and which methods it offered.
Passwords that start or end with a space are saved as typed. If an older save trimmed one, enter it again.
Mailbox fetching only runs when Enable support tickets is on and the cron job runs every minute.

Permission errors on storage#

If pages fail with write errors, or logs and uploads are not saved, the web server cannot write to storage/ or bootstrap/cache/. Make both writable by the web server user (the installer suggests chmod 775).

Docker: files in /data cannot be written#

The container gives /data to the user set by PUID and PGID (default 1000) when it starts as root. If you run it as a different user with --user, that step is skipped, so make /data writable for that user yourself.

Plugin upload fails#

Upload failed messages mention upload_max_filesize and post_max_size. Raise them in php.ini. The Docker image sets both to 16M.
Without the PHP zip extension, unzip the plugin by hand into plugins/<slug>/ and press Enable.
If the plugins folder is not writable, make it writable, set BILLING_EXTRA_PLUGINS_PATH to a writable folder, or upload by FTP.
Uploading can be turned off by BILLING_ALLOW_PLUGIN_UPLOAD=false in .env.

Run this on the server with the user's email address:

php artisan billing:reset-2fa [email protected]

Add --revoke-tokens to also revoke that user's API tokens.

Chinese, Japanese or Korean text prints as empty boxes in PDFs#

The PDF library has no glyphs for those scripts until you install the optional font packs, from Settings → System or with php artisan billing:fonts:install. See PDF and fonts.