Troubleshooting — common issues + fixes

Could be: account locked after 5 failed attempts (wait 30 min or ask super_admin to unlock); account marked inactive (super_admin → Users → re-activate); email mismatch (case-insensitive but trailing spaces matter — re-type).

Default session TTL is 8 hours of inactivity. If you're hitting this within shorter periods: browser blocking cookies (check site settings); cross-domain issue if accessing via different URLs; storage/sessions/ not writable to web user (check permissions).

(1) Check spam folder. (2) Confirm SMTP is configured: Settings → Communication → Send test email. (3) Check email_log for failed sends — DKIM/SPF likely cause if Gmail/Outlook bouncing. (4) Confirm user's email is correct in Users table.

(1) Settings → Company Profile → Branding — re-upload logo. (2) Check storage/uploads/brand/ + public/uploads/brand/ exist + readable. (3) Clear PDF cache: super_admin button on Settings → File Vault → Maintenance. PDFs re-render fresh.

Almost always a custom-template issue. The dompdf-safe rules (chapter 8 of finance manual): table-layout fixed, HTML width attrs not CSS %, no position:fixed. Revert template to default + verify.

Settings → Company Profile → About → re-enter VAT TRN. Save. Bust PDF cache. Re-render.

(1) Settings → Communication → verify SMTP host/port/user/password. (2) Check encryption (TLS or SSL?). (3) config/communication.local.php exists + has correct values? (4) Check email_log for the test send + error message. (5) Firewall / port blocking outbound 587/465?

DKIM + SPF not configured on the firm's domain. Talk to IT / hosting provider. 30 min setup, dramatic deliverability improvement.

cron-m17-email-queue.php not running. Check crontab. Run manually: php bin/cron-m17-email-queue.php. Check email_queue table for stuck rows.

Setting m11.require_job_completion_for_invoice is ON. Either complete the job first, or flip the setting OFF for phased-billing engagements.

Job state machine rejects skip-states. e.g. not_started → completed directly is rejected; must go through in_progress first.

Setting m13.lifecycle.block_archive_until_settled protects against accidental archival. Complete the offboarding workflow first (final settlement marked paid → status = settled). Then delete is allowed.

Sign-off chain enforces order. Cannot sign as reviewer until preparer signs. Cannot sign as manager until reviewer signs. Etc. Check the sign-off ribbon — current stage is glowing.

(1) RBAC scope — your role may have department/assigned scope; the new record may be outside your scope. (2) Filter applied — clear filter strip. (3) Soft-delete — toggle "Show deleted" if available.

Atomic counters increment even on rollback. So if a job-create fails mid-transaction, the sequence number is consumed. Audit-log explains what happened. Sequence integrity is preserved (no duplicates ever).

(1) Check for un-allocated payments (payment.is_advance=1). (2) Refresh — balance computed live from balance_due column. (3) Run Reports → AR Aging Detail · Σ should equal client's outstanding total.

Forecast widget queries can be heavy with many invoices. Disable the widget temporarily via Settings → Dashboard. If others are slow: check DB indices (migration drift), check php-fpm worker count, check storage IO.

Expected — dompdf builds + caches. Subsequent loads are sub-100ms from cache. If always slow, check storage/invoices/ writable + free space.

Storage failure during write. Re-run backup manually: php bin/cron-backup.php. Investigate disk health on backup-target volume.

(1) Check rclone config — credentials still valid? (2) Check remote quota — out of space? (3) Network — firewall blocking? (4) Run manually: ./bin/cron-offsite-backup.sh. Logs at /var/log/acwms/offsite.log.