---
title: 12.04 Troubleshooting Common Issues
description: Diagnostic playbook for the most common SimpleRisk operational issues — install errors, login problems, cron jobs not firing, slow performance, broken…
---
[Skip to content](https://support.simplerisk.com/kb/12-04-troubleshooting-common-issues#main-content)
English
Show submenu for translations
[Customer portal](https://support.simplerisk.com/tickets?hsLang=en)
[](https://www.simplerisk.com/)
Open main navigation
Close main navigation
- English
Show submenu for translations
- [Customer portal](https://support.simplerisk.com/tickets)
- [Contact us](https://www.simplerisk.com/about-us/contact-us)
[Contact us](https://www.simplerisk.com/about-us/contact-us)
How can we help you?
- There are no suggestions because the search field is empty.
1. [SimpleRisk Knowledge Base](https://support.simplerisk.com/kb?hsLang=en)
2. [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en)
3. [12 Operations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#12-operations)
# 12.04 Troubleshooting Common Issues
## Diagnostic playbook for the most common SimpleRisk operational issues — install errors, login problems, cron jobs not firing, slow performance, broken email, encryption-related issues, integration failures. Each issue includes likely causes and the specific commands or settings to check.
## Why this is a reference article
This article is a runbook. When something breaks, find the symptom in the table of contents below, jump to the section, work through the diagnostic steps. The patterns recur; once you've debugged each one once, the second time is fast.
## Issue 1: Install fails with "Database connection error"
**Symptom**: the installer can't connect to the database; the install can't proceed.
**Likely causes** (in order of frequency):
1. **Wrong credentials** in `simplerisk/includes/config.php`. Verify by trying the credentials manually: `mysql -u {user} -p -h {host}`.
2. **Database server unreachable**. Check network: `nc -zv {host} 3306` should succeed.
3. **Database user doesn't have access** from the SimpleRisk server's IP. Check `SHOW GRANTS FOR '{user}'@'{simplerisk-ip}';`.
4. **Database doesn't exist**. The configured `simplerisk` database needs to exist. Create with `CREATE DATABASE simplerisk;`.
5. **MySQL version too old**. SimpleRisk requires MySQL 5.7+. Check with `mysql --version`. (MariaDB is no longer supported — see [System Requirements](https://support.simplerisk.com/kb/01-01-system-requirements?hsLang=en).)
## Issue 2: User can't log in (correct credentials)
**Symptom**: user enters correct username and password, login fails.
**Likely causes**:
1. **Account is locked** (failed-attempts threshold reached). Check `SELECT lockout FROM user WHERE username = '{user}';`. If `1`, unlock via User Management or `UPDATE user SET lockout = 0 WHERE username = '{user}';`.
2. **Password expired** (password policy enforces expiration). Force a password change via the admin reset path.
3. **MFA misconfigured** (user enrolled but lost device). See [Multi-Factor Authentication](https://support.simplerisk.com/kb/04-02-multi-factor-authentication?hsLang=en) recovery procedure.
4. **SSO misconfigured** (the user is `type='ldap'` or `type='saml'` and the SSO path is broken). Test SSO directly; check the Authentication Extra's settings.
5. **Session storage is broken** (database can't write `sessions` rows). Check database disk space and table integrity.
## Issue 3: Cron jobs aren't firing
**Symptom**: workflows don't fire, notifications don't send, AI jobs queue indefinitely.
**Diagnostic steps**:
1. **Check cron daemon is running**: `systemctl status cron` (or your distribution's equivalent).
2. **Check the SimpleRisk cron entries**: `crontab -l` (under the user that runs SimpleRisk's cron).
3. **Check `cron_history` table**: most recent entries should be within the expected interval.
4. **Check the debug log**: cron job runs log entries; failures log errors. Filter for the specific job's output.
5. **Run the cron job manually**: `php /path/to/simplerisk/cron/cron_notification.php` (or the relevant script). Observe the output for errors.
6. **Check filesystem permissions**: the cron user needs read/write access to `simplerisk/`.
For the cron queue worker specifically: check that `cron_queue_worker.php` is running. On some installs it runs continuously; on others it's invoked by cron.
## Issue 4: Slow page loads
**Symptom**: pages take \> 5 seconds to load.
**Diagnostic steps**:
1. **Identify which pages are slow**: all pages, or specific ones?
2. **Check PHP opcache**: `php -i | grep opcache.enable` should show `On`. See [Performance Tuning](https://support.simplerisk.com/kb/12-02-performance-tuning?hsLang=en).
3. **Check PHP-FPM worker status**: `pm.max_children` saturation produces queueing.
4. **Check MySQL slow query log**: enable, capture queries from a slow page load, identify the culprit.
5. **Check server resources**: `top`, `free -h`, `df -h`. Saturated CPU, OOM, or full disks all produce slowness.
6. **Check database server resources** if separated.
For specific slow operations, see [Performance Tuning](https://support.simplerisk.com/kb/12-02-performance-tuning?hsLang=en).
## Issue 5: Notifications not arriving
**Symptom**: SimpleRisk should send an email, the email doesn't arrive.
**Diagnostic steps**:
1. **Check your notification center.** A queued email that fails every delivery attempt raises an "Email Delivery Failed" notification. It goes to whoever triggered the send when SimpleRisk knows who that was, and to all admins otherwise — a cron-driven send has no session, so those land with the admins. Read it carefully, though. The notification appears only after the queue has exhausted its retries (six attempts across roughly five minutes), so a failure you're chasing in real time won't be there yet, and a single notification stands for every delivery failure aimed at the same target in the same hour. It tells you delivery is broken. It doesn't tell you how many messages are affected, and it ages out after seven days by default, so a week-old outage nobody looked at leaves a clean-looking notification center behind. That window is **Email Delivery Failure Notification Retention** on the **Mail** settings page if seven days is the wrong fit for how often your team checks.
2. **Check the Queue Monitor**: Settings cog → Settings Hub → **Queue Monitor** tile. Filter Status to `failed` and look for `core_email_send` rows. The Payload column carries each task's recipient address, subject, and body, so this is where you find out *which* messages failed rather than just *that* mail is broken. The Attempts column tells you whether a task burned its whole retry budget or is still working through it.
3. **Check SMTP configuration**: Settings cog → Settings Hub → **Mail** tile. Send a test email; observe.
4. **Check the test email succeeded**: if not, the SMTP configuration is wrong.
5. **Check the Notification Extra is active**: Settings cog → Settings Hub → **Extras** chip → **Notification Extra** tile.
6. **Check the notification cron is running**: `cron_notification.php` writes to the debug log on each run.
7. **Check the notification queue**: `notification_sent_log` table for queued-but-not-sent entries.
8. **Check the recipient's spam folder**: deliverability issues sometimes look like non-delivery.
9. **Check the SMTP service's delivery logs**: bounces, suppressions, rate limits.
One caveat on steps 1 and 2 after an upgrade: the queue worker is a long-running process, so it keeps running whatever code it started with. Until it recycles, delivery failures may not surface as notifications at all. If mail broke right after a deploy and the notification center is silent, restart the worker before you trust its silence.
For SMTP-side issues, see [Email and the Notification Extra](https://support.simplerisk.com/kb/07-02-email-and-the-notification-extra?hsLang=en).
## Issue 6: Encrypted data displays as ciphertext
**Symptom**: risk subjects, descriptions, etc. display as long base64-looking strings instead of readable text.
**Likely causes** (when the Encryption Extra is active):
1. **Master key file missing or wrong** on the server handling the request. Check `simplerisk/extras/encryption/includes/init.php` exists and contains the expected key.
2. **Multi-server deployment with key file inconsistency**. One server has the right key; others don't. Check all servers.
3. **Master key file corrupted**. Restore from your backup of the key file.
Without the master key, the data can't be decrypted. See [Key Management and Rotation](https://support.simplerisk.com/kb/09-03-key-management-and-rotation?hsLang=en).
## Issue 7: Workflow / AI jobs queued but not processing
**Symptom**: workflows fire (workflow\_executions row created) but never complete; AI jobs queue but don't return results.
**Diagnostic steps**:
1. **Check the cron queue worker is running**: `cron_queue_worker.php` should be invoked regularly (or running continuously, depending on the install).
2. **Check `workflow_executions.status`**: stuck `pending` indicates the worker isn't picking up jobs; `failed` indicates execution errors.
3. **Check the debug log**: worker errors log there.
4. **Check the worker's process**: `ps aux | grep cron_queue_worker` should show it running (if continuous mode).
5. **For AI specifically**: verify the AI provider's API is reachable and the API key is valid (test via curl).
## Issue 8: Database disk filling up
**Symptom**: monitoring alerts on database disk approaching full.
**Diagnostic steps**:
1. **Identify the largest tables**: `SELECT table_name, ROUND((data_length + index_length) / 1024 / 1024) AS size_mb FROM information_schema.tables WHERE table_schema = 'simplerisk' ORDER BY size_mb DESC LIMIT 10;`.
2. **Common offenders**: `audit_log`, `debug_log`, `sessions` (if not cleaned up), `notification_sent_log`.
3. **For audit/debug logs**: define and apply retention policy.
4. **For sessions**: ensure session GC is running; manually purge old: `DELETE FROM sessions WHERE access < UNIX_TIMESTAMP() - 86400;`.
5. **Coordinate with operations**: increase storage, archive old data, or both.
## Issue 9: Integration receives 401 / 403
**Symptom**: API integration that worked yesterday returns 401 or 403 today.
**Likely causes**:
1. **API key revoked or rotated** without updating the integration.
2. **User account disabled** (the user the key belongs to).
3. **API toggle disabled**: Settings cog → Settings Hub → **Security** tile → check `Enabled` under the API section.
4. **Permission revoked** for the user (returns 403).
5. **Hitting a path the user can't see** (team filtering returns 403 or 404).
Check the SimpleRisk debug log for authentication failure entries; check the user's status; verify the key against current `api_keys`.
## Issue 10: Upgrade fails partway
**Symptom**: SimpleRisk upgrade flow fails mid-process; install left in inconsistent state.
**Diagnostic steps**:
1. **Read the upgrade error message** carefully. Most upgrade failures are specific (database constraint, missing PHP extension, schema change conflict).
2. **Check the upgrade function** in `simplerisk/includes/upgrade.php` for the version that failed; trace the specific operation.
3. **Restore from backup** if data integrity is at risk. See [Database Backup and Restore](https://support.simplerisk.com/kb/02-05-database-backup-and-restore?hsLang=en).
4. **Re-run the upgrade** after fixing the cause; SimpleRisk's upgrade flow is idempotent in most cases.
5. **Contact support** if the upgrade can't be made to complete; see [When to Contact Support](https://support.simplerisk.com/kb/12-05-when-to-contact-support?hsLang=en).
## Issue 11: SAML / LDAP authentication broken
**Symptom**: SSO users can't log in; local users still can.
**Diagnostic steps**:
1. **Check the Authentication Extra is active**: Settings cog → Settings Hub → **Extras** chip → **Authentication Extra** tile.
2. **Test SAML / LDAP configuration**: the Extra exposes test buttons; use them.
3. **Check the IdP side**: SAML metadata expired? LDAP service account credentials rotated? Network connectivity to the IdP?
4. **For SAML**: certificate expirations are common. Check `SAML_METADATA_URL` returns valid metadata.
5. **For LDAP**: the **Test Configuration** button on the Extra's settings page reports the specific failure.
6. **Check the debug log** for SSO-related error entries.
If users are locked out entirely (SSO broken, no local accounts), the recovery path is to log in as the original local admin (whose credentials predate SSO activation).
## Issue 12: Custom fields disappeared after upgrade
**Symptom**: after upgrade, custom fields aren't appearing on forms.
**Diagnostic steps**:
1. **Check the Customization Extra is still active**: upgrades occasionally deactivate Extras; reactivate.
2. **Check `custom_fields` table**: the field definitions should be present.
3. **Check the form layout template** in `custom_template`: layout may need to be re-saved.
4. **Reload the page**: browser cache may be serving an old form.
Custom fields rarely disappear on upgrade; if they do, restore the Customization Extra's data from backup.
## Generic diagnostic checklist
For any issue not covered above:
1. **What changed recently?** Software upgrade, configuration change, infrastructure change, traffic shift.
2. **What does the debug log say?** Filter by time range around when the issue started.
3. **What does the audit log say?** Specific to entity-state issues.
4. **What does the web server log say?** PHP errors, 5xx responses.
5. **What does the database log say?** Slow queries, connection errors, errors.
6. **Can you reproduce in non-production?** If yes, debug there.
7. **Does the issue affect all users or specific ones?** If specific, what's different about them?
8. **Does the issue happen at specific times?** If yes, correlate with cron schedules, backup windows, traffic patterns.
## Common pitfalls
A handful of patterns recur with troubleshooting.
- **Restarting before debugging.** Restart often hides the cause; debug first, restart after.
- **Trying multiple fixes simultaneously.** When something works, you don't know which fix did it. Fix one thing at a time.
- **Trusting user reports over evidence.** "It's broken" needs a reproducer. Get specifics before debugging.
- **Skipping the logs.** The logs usually contain the answer. Always check them first.
- **Treating intermittent issues as fixed when they don't repeat for an hour.** Intermittent issues recur. Document and continue investigating.
- **Not coordinating with the program team.** A "just trying to fix this" change in production during a workflow can disrupt users.
- **Not having a rollback path.** Before any production change, know how to undo it.
- **Forgetting to monitor after the fix.** A fix that "works" then breaks again two hours later wasn't actually a fix.
- **Documenting fixes only in chat.** Future operators (and you in 6 months) will need to find this. Document properly.
- **Not asking for help when stuck.** [When to Contact Support](https://support.simplerisk.com/kb/12-05-when-to-contact-support?hsLang=en).
## Related
- [Monitoring SimpleRisk](https://support.simplerisk.com/kb/12-01-monitoring-simplerisk?hsLang=en)
- [Performance Tuning](https://support.simplerisk.com/kb/12-02-performance-tuning?hsLang=en)
- [Scaling Considerations](https://support.simplerisk.com/kb/12-03-scaling-considerations?hsLang=en)
- [When to Contact Support](https://support.simplerisk.com/kb/12-05-when-to-contact-support?hsLang=en)
- [The Debug Log](https://support.simplerisk.com/kb/11-02-the-debug-log?hsLang=en)
- [The Audit Trail](https://support.simplerisk.com/kb/11-01-the-audit-trail?hsLang=en)
- [The Cron Jobs](https://support.simplerisk.com/kb/02-07-the-cron-jobs?hsLang=en)
- [Database Backup and Restore](https://support.simplerisk.com/kb/02-05-database-backup-and-restore?hsLang=en)
- [FAQs](https://support.simplerisk.com/kb/faqs?hsLang=en)
- [SimpleRisk Extras](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#main-content)
- [Vulnerability Management Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#vulnerability-management-extra)
- [Team Separation Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#team-separation-extra)
- [Import-Export Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#import-export-extra)
- [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#main-content)
- [00 About This Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#00-about-this-guide)
- [01 Installation and Deployment](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#01-installation-and-deployment)
- [02 Upgrades and Maintenance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#02-upgrades-and-maintenance)
- [03 Users and Permissions](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#03-users-and-permissions)
- [04 Authentication](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#04-authentication)
- [05 Customization](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#05-customization)
- [06 Configuring Risk and Compliance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#06-configuring-risk-and-compliance)
- [07 Integrations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#07-integrations)
- [08 The API](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#08-the-api)
- [09 Encryption and Data Security](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#09-encryption-and-data-security)
- [10 Workflows and Automation](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#10-workflows-and-automation)
- [11 Reporting and Auditing](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#11-reporting-and-auditing)
- [12 Operations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#12-operations)
- [13 Reference](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#13-reference)
- [User Guide](https://support.simplerisk.com/kb/user-guide?hsLang=en#main-content)
- [00 Foundations of GRC](https://support.simplerisk.com/kb/user-guide?hsLang=en#00-foundations-of-grc)
- [01 Risk Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#01-risk-management)
- [02 Compliance Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#02-compliance-management)
- [03 Governance](https://support.simplerisk.com/kb/user-guide?hsLang=en#03-governance)
- [04 Asset and Data Inventory](https://support.simplerisk.com/kb/user-guide?hsLang=en#04-asset-and-data-inventory)
- [05 Threat and Vulnerability Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#05-threat-and-vulnerability-management)
- [06 Assessments](https://support.simplerisk.com/kb/user-guide?hsLang=en#06-assessments)
- [07 Incident Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#07-incident-management)
- [08 Audit and Reporting](https://support.simplerisk.com/kb/user-guide?hsLang=en#08-audit-and-reporting)
- [09 Day-to-Day SimpleRisk](https://support.simplerisk.com/kb/user-guide?hsLang=en#09-day-to-day-simplerisk)
- [10 Continuous Improvement](https://support.simplerisk.com/kb/user-guide?hsLang=en#10-continuous-improvement)
- [SimpleRisk User Guides](https://support.simplerisk.com/kb/simplerisk-user-guides?hsLang=en)
- [Troubleshooting](https://support.simplerisk.com/kb/troubleshooting?hsLang=en)
- [SimpleRisk Hosted](https://support.simplerisk.com/kb/simplerisk-hosted?hsLang=en)
- [How To videos](https://support.simplerisk.com/kb/how-to-videos?hsLang=en)
[](https://www.simplerisk.com)
Copyright © 2026, SimpleRisk, Inc.