Troubleshooting

Research stays queued

Make sure both the web application and pnpm worker are running against the intended PostgreSQL database. The web process can accept a run without executing it. Check that migrations and an active runtime configuration exist.

Do not repeatedly create new runs to test whether the queue is moving. Each run can consume provider usage once a worker claims it.

The browser says disconnected

A lost event stream means the browser cannot currently confirm live activity. It does not prove that the worker stopped. Reconnect or return to the saved run using the same owner session; the interface can restore persisted events and output.

If the browser shows a terminal failure, inspect that persisted error rather than interpreting an old active stage as current work.

A source is unavailable

Read the saved warning and the source record’s status, scope and dates. Transient failures can trigger bounded retries, but permanent failures, disabled adapters and missing linkage are not cured by a model rewrite.

For BAG or 3DBAG, distinguish an address-linkage failure from a network timeout. For PVGIS, confirm that coordinates and planned power were supplied. For grid context, check exact confirmed postcode matching and the source-access switch without assuming that enabling it resolves licensing.

Do not replace unavailable evidence with an example value. A source outage is a limitation, not a negative finding about the property.

A supported review still fails

The reviewer judgment is only one condition. Code can still reject an empty, duplicate, unavailable, unrelated or wrongly mapped reference. Failure details include those additional reasons.

An available source elsewhere in the section does not repair a missing claim-level reference. Correct the sentence and exact citations, or disclose that the fact remains unknown. See Quality gates.

A report remains blocked after repair

The simplified workflow does not repair indefinitely. After its permitted correction, unresolved failures remain visible. This is intentional: publication as a validated result must not be obtained by lowering thresholds or removing citations.

An uncited conditional assertion can still be factual. For example, stating that a particular use depends on operator confirmation requires support when presented as a site or eligibility rule. A genuinely fact-free request to ask the operator is different.

Old dates appear in a new run

That can be correct. A historical model release, publication date or reused cached observation must not be relabeled as current merely because a new report was requested. Inspect freshnessBasis and the relevant observation or publication date, not retrieval alone.

Authentication or download fails

Check AUTH_COOKIE_SECRET, the request origin and the retained owner cookie. A different browser session does not gain access merely by knowing the report URL. Production and nonlocal bootstrap require the configured access credential; local development bootstrap is not public authentication.

Do not expose a run or PDF endpoint without ownership checks as a workaround. Admin credentials and provider keys must remain server-side.

Changes are not used by new research

Publishing a prompt and reloading worker code solve different problems. Confirm the run’s configuration version, then ensure an idle worker was restarted after code changes. Drain active jobs before stopping a process.

For targeted verification:

pnpm typecheck
pnpm test
pnpm test:graph

Test outcomes describe their actual environment and inputs. Passing deterministic tests does not guarantee that an external service is available or that every future model-written report will pass validation.