Skip to content

Troubleshooting

Application database unavailable

Symptoms include empty pages, 503, or “Application database unavailable.”

  1. Verify PHP has pgsql.
  2. Test localhost:5432, database jasper_reports, user postgres.
  3. Inspect PHP/Apache logs.
  4. Replace the committed password in config.php.

Do not set JRS_DB_HOST/PORT/NAME/USER/PASS; current code ignores them despite stale installer/README messages.

Missing tables or scheduler fields

Apply database/schema.sql to the application DB. It creates five tables only. If repeat/hourly/daily/weekly/monthly/once selections do not persist as expected, inspect jasper_schedule: the supplied schema lacks all newer mode fields, and no migration runs automatically. See Database before adding columns.

Central login loops or 401/403/503

  • Confirm CENTRAL_DATABASE_URL or JRS_AUTH_DATABASE_URL reaches the database containing Central tables.
  • Confirm acugis_session is visible at the Jasper path and unexpired.
  • Confirm JRS_AUTH_SEARCH_PATH when tables are outside the default path.
  • Verify service resource service:jasper_reports and report resource permissions.
  • Enable JRS_AUTH_DEBUG=1 briefly and inspect [jrs-auth] logs or /debug/session.php; disable it afterward.

No Central DSN means auth is disabled/local-admin, not “Central unavailable.” Set JRS_NO_APP_DB_FOR_CENTRAL=1 when an unintended app-DB fallback obscures a remote Central configuration problem.

No datasources

  • Confirm jasper_datasource exists in JRS_DB_SCHEMA (default public) and has enabled=true rows.
  • Confirm names are nonempty and unique.
  • Regenerate docker/report-server/context.xml.
  • Restart Tomcat after changing context.

The UI error mentioning JRS_DB_* is stale.

Context generation fails

reports/generate_jasper_context.php requires Central login/service edit permission when auth is configured, at least one datasource, and a writable JRS_JASPER_CONTEXT_PATH parent.

The generated XML contains clear-text datasource passwords. Restrict it and ensure XML-special characters are escaped by using the generator.

Tomcat fails to start

  • Supply every bind-mounted Compose file: WAR, JDBC 42.7.3 JAR, and context XML.
  • Run docker compose config from docker/report-server.
  • Inspect docker compose logs report-server.
  • Ignore the stale DOCKER.md ./config volume instructions; current Compose mounts only context.xml.
  • Check the unusual report mount path expected by the current Compose/WAR combination.

Report not found or JNDI lookup fails

  • Confirm <report-key>.jrxml or .jasper exists under docker/report-server/reports.
  • Confirm the JSON report key matches the normalized file basename.
  • Confirm _dataSource exactly matches a generated jdbc/<name> resource.
  • Ensure the container can resolve/reach the datasource host; use host.docker.internal only where supported/configured.
  • Check Tomcat logs for resolved report directory/name and JNDI errors.

Jasper proxy errors or timeouts

The PHP proxy calls JRS_JASPER_INTERNAL_REPORT_URL with a 600-second timeout and does not follow redirects. Check:

curl -v "http://127.0.0.1:9099/report?_repName=REPORT&_dataSource=DS&_repFormat=pdf"

Direct testing bypasses PHP ACLs; perform it only from a trusted host. Confirm Tomcat listens on 9099, the WAR is ROOT, and firewall/container networking permits access.

SQL-backed parameters are empty

  • Run the SQL manually against the report datasource.
  • Confirm the definition uses source: "sql:...".
  • One result column maps to identical label/value; two or more map first column to label and second to value.
  • Use a read-only database role and review query cost.
  • Check parameter names/types against JRXML. Repeated query parameters become collections; the servlet has a special collection override only for p_boro.

Schedule save or timer install fails

  • Confirm exec() is enabled.
  • Confirm /opt/qcarta-jasper-service/systemd and the schedule directory are writable by PHP.
  • Confirm sudo -n works for required systemd/file commands.
  • Confirm JRS_JASPER_SYSTEMCTL points to a valid executable.
  • Inspect PHP error log for [jrs-schedule-systemd].
  • Inspect generated <id>_env.sh, .service, .timer, and symlinks.

JRS_JASPER_SYSTEMD_USE_SUDO and JRS_JASPER_SYSTEMD_UNIT_DIR do not work as overrides. Current values are hardcoded to true and /opt/qcarta-jasper-service/systemd.

Schedule run fails

Check schedules/logs/schedule-<id>.log and jasper_schedule_execution.error_message.

  • “Database unavailable”: application DB connection/config.
  • “Report response is not a valid PDF/XLSX”: Tomcat returned an error/HTML body despite success status.
  • Output not writable: recursively assign www-data:www-data and mode 775 to schedule storage.
  • HTTP error: inspect the logged request URL and Tomcat logs; it can contain sensitive parameter values.
  • Manual run can exceed web proxy timeouts because it executes synchronously.

Email fails

  • Validate comma/semicolon/whitespace-separated recipient addresses.
  • Confirm attachment exists and is readable.
  • With empty JRS_SMTP_HOST, verify local PHP mail()/MTA.
  • With SMTP, verify host/port and AUTH LOGIN credentials.
  • The built-in SMTP client does not support STARTTLS; use a local relay rather than an Internet submission endpoint requiring TLS.
  • Confirm the selected template exists under email_tmpl/.

Disk or log growth

No retention, cleanup, or log rotation exists. Review schedules/output, schedules/logs, container logs, and execution rows. Introduce platform-managed retention only after confirming audit and recovery requirements.

Unsafe diagnostics

Block or remove debug.php and debug/param_pipeline_php.php; the former exposes sensitive session/database information. Keep /debug/session.php disabled (JRS_AUTH_DEBUG unset) except during controlled diagnosis.