Troubleshooting

The container will not start

Log message	Cause	Fix
JIRA_CREDENTIAL_ENCRYPTION_KEY must be set to a base64-encoded 256-bit key	The variable is missing or empty.	Set it. Generate with openssl rand -base64 32.
JIRA_CREDENTIAL_ENCRYPTION_KEY must decode to a 256-bit key	The value is a passphrase, not a base64-encoded 32-byte key.	Generate a proper key; an arbitrary string will not work.
finding.fingerprint.hmac-secret must be configured	Running the prod profile without FINDING_FINGERPRINT_HMAC_SECRET.	Set it, and keep it stable - see Production Deployment.
A Flyway validation or migration failure	The database schema does not match the image, usually after starting an older image against a newer schema.	Restore the database backup taken before the upgrade. Migrations are forward-only.

Everything disappears when I restart

You are running on the default profile with an in-memory H2 database. Set SPRING_PROFILES_ACTIVE=prod and point the scanner at PostgreSQL. See Production Deployment.

Sign-in fails

• Redirected back to the sign-in page in a loop - the issuer URI the browser is sent to and the one the backend validates against must be the same URL. A container-internal hostname in OIDC_ISSUER_URI breaks this: users' browsers cannot reach it.
• Signed in, but every page says access is denied - the roles claim is not where the backend looks, so the token carries no role the backend recognises and every request comes back as HTTP 403 with a sanitized access-denied body. Decode the access token and check that the path in APP_SECURITY_ROLES_CLAIM (default realm_access.roles) actually contains the roles.
• Signed in, but the page says the account has no access - the account holds neither the user nor the admin role, so it is refused everywhere. Grant it the role named by APP_SECURITY_USER_ROLE (default USER) or APP_SECURITY_ADMIN_ROLE (default ADMIN) and sign in again.
• Signed in, but almost nothing is there - the user holds USER and not the admin role, so the navigation shows only the read-only pages: the risk dashboard, findings, and suppressions. The admin role name is configurable via APP_SECURITY_ADMIN_ROLE (default ADMIN).

The Jira connection test fails

The test reports a sanitized error - credentials never appear in errors or logs - so check in this order:

1. Reachability - can the scanner container reach the Jira base URL? Test from inside the container, not from your laptop. Proxies and egress firewalls are the usual cause.
2. TLS - a Jira instance with a private CA certificate needs that CA trusted by the container's JVM truststore.
3. Credentials - the service account username plus an API token or password. If the account has SSO-only login, issue a token instead.
4. Permissions - the account needs Browse Projects on every project in scope. A test that passes but scans that find nothing usually means the account can log in but sees no projects.

A scan finds nothing, or far fewer issues than expected

• The service account cannot browse the projects in scope. Confirm the project list under Scope preview on the scan configuration.
• The field selection excludes the fields that hold the content. Check included and excluded fields, and whether comments are included.
• Many rules are seeded inactive on purpose. See Built-in rules for which ones and why.

A scheduled scan did not run

Open the scan configuration and check the schedule panel:

• Last scheduled run shows a skip because a scan of the same configuration was still running. Scheduled runs never overlap - the tick is skipped, and the skip is written to the audit log as SCAN_SCHEDULE_SKIPPED.
• Last scheduled run shows a skip because the fire time fell outside every allowed scan window. The tick is skipped rather than postponed, so a cron expression that never coincides with a window never runs. Compare the two - they are configured independently.
• Cron expressions use six fields (second minute hour day-of-month month day-of-week), and are evaluated in the server's time zone.

Attachments are not being scanned

• Attachment scanning is off unless Scan attachment contents is enabled on the scan configuration.
• It also requires the SCAN_ATTACHMENTS license feature. Without it, the scan completes normally over fields and comments and reports: "Attachment scanning is not included in your license; attachments were not scanned."
• Individual attachments are skipped for documented reasons - unsupported format, encrypted, too large, parse timeout. See Attachment scanning.

Report e-mails are not arriving

• Use Send a test e-mail on Administration -> Reporting first; it isolates SMTP problems from reporting logic.
• Recipients are resolved from Jira project leads. Check that the service account has the Browse users and groups global permission and that Jira's User email visibility is Logged in users only or Public. A project whose lead has no address, or whose address Jira hides, is counted under projects without owner e-mail on the latest run.
• Recipients with no open findings are skipped deliberately - the run counts them as skipped rather than sending an empty report.
• Links in the e-mail point at APP_BASE_URL. If recipients get localhost links, that variable is unset.

New scans report old findings as new

FINDING_FINGERPRINT_HMAC_SECRET changed. Finding identity is derived from it, so the previous review decisions and suppressions no longer match. Restore the original secret if you still have it.