Troubleshooting FAQ

Troubleshooting FAQ

The ten symptoms that account for most lost hours, in plain language.

Canonical source: references/gotchas.md (60+ issues indexed by symptom) and references/jr7-valid-elements.md. This page is the curated on-ramp.

1. My report deploys fine but running it returns an opaque 400

JasperReports Server 10's strict Jackson parser rejects unknown jrxml elements at fill time, not at compile time — a clean local compile proves nothing. Classic offenders: 6.x-era elements in a JR7 file, isDefault on a .jrtx style (must be default="true"), pie seriesColors, line/area plot properties. Fix: run lint_jrxml.ps1 before deploying — it catches these statically (and runs automatically inside deploy_report.ps1).

2. My query works in psql but the report fails at fill time

If the query starts with WITH (a CTE), the server's SQL security validator rejects it — another generic 400. Fix: rewrite the CTE as a nested FROM subquery so the statement starts with SELECT. Verify in psql that results are identical first.

3. I created a dashboard via the REST API and it renders blank

A hand-built dashboard model PUT to /rest_v2/resources stores successfully (201) and renders nothing. Dashboards must go through the export → inject → import flow. Fix: use compose_dashboard.ps1 / build_dashlets.ps1 -Compose.

4. Ad hoc view returns 500 "bytes is null"

Same root cause as #3 — ad hoc views can't be PUT either. Fix: manage_adhoc.ps1 (import pattern).

5. I get 403 trying to modify a report that deployed fine yesterday

The report has become a dashlet — reports referenced by a dashboard are modification-locked until the owning dashboard is deleted. Fix: teardown_dashboard.ps1, edit, recompose.

6. curl from PowerShell mangles my JSON body (400 serialization.error)

Windows PowerShell 5.1 rewrites inline quotes. Fix: always pass bodies from a file: --data "@req.json". Also build URLs with ${var} braces — ? is a variable-name character in PS 5.1.

7. After an upgrade, the login page just errors out

The server can't find its keystore. $HOME/.jrsks and .jrsksp (of the OS user who installed the server) were not carried to the new environment. Fix and prevention: Upgrade Hub — the two blockers. If an upgrade ever prompts you to create a keystore: abort — continuing corrupts the repository.

8. PDF/DOCX export produces nothing on my new server

From ~7.8 onward the export engine is Chrome/Chromium, and it's an install-time dependency. No Chromium configured = no PDF export. Configure the browser path in js.config.properties.

9. Which port is JasperReports Server on?

In this project's environment: 8081 (/jasperserver-pro). A different, unrelated service answers on 8080 and 401s everything — a classic time sink.

10. My deploy failed and the script output doesn't say why

The real error is usually in the server response body, not the script's stdout. The skill's Assert-JrsOk prints a pointer into gotchas.md for known symptoms. When filing an issue, always include the response body — the bug template asks for it.

---

Not here? Search gotchas.md by symptom text, then open an issue — fixes contributed back become linter rules where possible, so nobody debugs the same thing twice.