Skip to main content

Troubleshooting

This page covers the most common issues encountered in Gäld self-hosted installations and how to resolve them. For the cloud (EE) version, contact support if an issue persists after following these steps.

Queue worker not processing jobs​

Symptoms: Recurring invoices not generated, reminder emails not sent, fiduciary export stuck.

Cause: The queue worker (Laravel Horizon or the queue:work process) is not running.

Fix:

# Check status
sudo systemctl status gaeld-worker

# Restart the worker
sudo systemctl restart gaeld-worker

# View recent failures
php artisan queue:failed

If you see failed jobs, retry them:

php artisan queue:retry all

To clear the failed jobs list after resolving the underlying issue:

php artisan queue:flush

See Self-Hosting for the full systemd service configuration.

MeiliSearch not available / search returns no results​

Symptoms: Contacts, invoices, or expenses cannot be found via the search bar; error message "Search unavailable".

Cause: MeiliSearch is not running, or the index has not been populated.

Fix:

# Check MeiliSearch status
sudo systemctl status meilisearch

# Restart MeiliSearch
sudo systemctl restart meilisearch

# Re-index all data (run from the application directory)
php artisan scout:import "App\Domains\Invoicing\Models\Invoice"
php artisan scout:import "App\Domains\Contacts\Models\Contact"
php artisan scout:import "App\Domains\Expenses\Models\Expense"
Fallback behaviour

If MeiliSearch is unavailable, Gäld falls back to database search automatically. Results may be slower and less fuzzy, but the application continues to function.

CAMT.053 import fails or produces no transactions​

Symptoms: Uploading a bank statement produces an error or imports 0 transactions.

Common causes and fixes:

CauseFix
File is not a valid CAMT.053 XMLCheck the file extension and confirm your bank exports CAMT.053, not CAMT.054 or MT940
File contains transactions for a different IBANAdd that IBAN as a bank account in Settings → Bank Accounts, then re-import
File has already been importedGäld detects duplicates by file hash — download a fresh export from your bank covering a different date range
XML is malformedOpen the file in a text editor and verify it starts with <?xml and contains <Document>

If the error persists, save the file and contact support — include the error message shown by Gäld.

Invoice PDF not generating / download is blank​

Symptoms: Clicking Download PDF on a finalized invoice produces a blank page or an error.

Cause: Usually a TCPDF configuration issue or a missing font.

Fix:

  1. Check the application log for PDF errors:
tail -n 50 storage/logs/laravel.log | grep -i pdf
  1. Ensure the storage/ directory is writable:
chmod -R 775 storage/
chown -R www-data:www-data storage/
  1. Run the post-install artisan commands:
php artisan storage:link
php artisan config:clear
php artisan cache:clear

Email not being sent (invitations, reminders, salary slips)​

Symptoms: Invited users do not receive invitation emails; payment reminders are not delivered.

Cause: Mail configuration is incorrect or the queue worker is not running.

Fix:

  1. Check Settings → Email for your SMTP configuration (host, port, username, password, encryption)
  2. Click Send Test Email to verify the mail connection
  3. Check the queue worker is running (see above)
  4. Check storage/logs/laravel.log for SMTP errors:
grep -i "swift\|smtp\|mail" storage/logs/laravel.log | tail -20

Common SMTP settings for Swiss providers:

ProviderHostPortEncryption
Infomaniakmail.infomaniak.com587STARTTLS
Hostpointmail.hostpoint.ch587STARTTLS
GMXmail.gmx.net587STARTTLS
Mailgunsmtp.mailgun.org587STARTTLS

"These credentials do not match our records" on login​

Symptoms: Cannot log in despite entering the correct email and password.

Possible causes:

  • The password was changed by another admin
  • 2FA is enabled and you are not entering the TOTP code
  • The account is on a different organisation's subdomain

Fix:

  1. Use Forgot password on the login screen
  2. If 2FA is the issue and you have lost your device, use a recovery code (issued when 2FA was set up)
  3. If you have no recovery codes, your organisation Owner must disable 2FA for your account under Settings → Users → [your name] → Disable 2FA

Year-end closing is greyed out / unavailable​

Symptoms: The Year-End Closing button in Accounting is not clickable.

Cause: One or more prerequisite checks have not passed. Gäld requires:

  • No unreconciled bank transactions for the fiscal year
  • No invoices in Draft status with a date in the fiscal year
  • The current user has Owner or Admin role

Fix:

  1. Go to Banking → Reconciliation and clear all unreconciled items
  2. Go to Invoices and finalize or cancel any drafts dated in the closing year
  3. Verify your role in Settings → Users

Artisan commands (self-hosted quick reference)​

# Clear all caches
php artisan optimize:clear

# Re-run migrations (safe to run repeatedly)
php artisan migrate

# Check application status
php artisan about

# Reindex search
php artisan scout:import "App\Domains\Invoicing\Models\Invoice"

# Retry failed queue jobs
php artisan queue:retry all

# View scheduled tasks
php artisan schedule:list

Contacting support​

If none of the above resolves your issue:

  • Community Edition: Open an issue on the GitHub repository with the error message and relevant log lines
  • Enterprise Edition: Use the Help → Contact Support button in the application (includes automatic system info)

When reporting a bug, always include:

  • Gäld version (visible in Settings → About)
  • PHP version (php -v)
  • Database version (psql --version)
  • The relevant section of storage/logs/laravel.log