Troubleshooting
Find missing evidence, invalid contracts, unavailable releases and unresolved outcomes
Begin with the saved prediction/forecaster record and its exact error, version and evidence release. Do not substitute invented probabilities or data when execution fails.
| Symptom | Check | Next action |
|---|---|---|
| Forecasting tools absent | Deployment forecasting setting and discover_capabilities | Ask the deployment operator to verify configured availability |
| Cannot create forecaster | Evidence query has a published release in the project | Validate/inspect its bindings and publish the actual query |
| Prompt rejected | Missing required or unknown template variables | Include subject_ref, horizon and evidence_json; use supported names |
| Input rejected | Resolved horizon/params and both forecaster/query schemas | Align fields/types; no automatic coercion/default insertion |
| P-101 query returns no row | Identity mapping and actual source subject values | Verify equipmentId → subject_ref and source endpoint |
| Wrong equipment included | Query root identity/filter and subject contract | Fix query and publish/re-pin deliberately |
| Empty/stale evidence yet completed | Evidence age, rows, diagnostics and hasMore | Treat output as limited; repair source coverage before reliance |
| Pinned release unavailable | Retired/deleted release or incompatible bindings | Verify current query, publish and explicitly re-pin a new version |
| Run rejected as inactive | Forecaster Active status and executable version | Review/save an active valid version |
| Model or budget failure | Runtime model credentials/access, limits and trace | Resolve the stated failure, then make a reviewed new run |
| Evaluation date rejected | horizonEndsAt must be future for new runs | Set a date consistent with actual invocation/window |
| Watchlist does not run | Enabled item, active forecaster, evaluation horizon, authorized scheduler | Inspect nextRunAt/lastRunAt and actual queued prediction |
| Cron timing differs | Current watchlist interval-label scheduler | Use hourly/daily/weekly; verify nextRunAt |
| Outcome remains pending | Due time, policy release, one explicit verdict, actual assertion IDs | Inspect outcome notes; fix evidence/configuration |
| Numeric score missing/fails | evaluationPolicy.forecastPath and numeric observedValue | Set $.value (or actual field) and submit explicit MCP evaluation |
| Report has no score | Eligible completed probability forecasts with binary evaluations | Record real observations; zero samples is not perfect quality |
Recover an interrupted external operation
Inspect the prediction's external operation history in the detail flow. A service may have performed work before a timeout/cancellation. Reconcile its actual result using the available operator workflow before rerunning; cancellation is not rollback of external side effects. Do not use database edits to mark an uncertain operation successful.
Diagnose evidence leakage
Compare invocation/cutoff time with source observation time and retained query evidence. A recorded cutoff does not automatically make a live source historical. Ensure a historical prediction uses records actually available at that time. A source snapshot hash identifies retained content; it does not prove the content was causally available before the event.
Information to retain
Keep prediction ID, forecaster/version, query release, subject/window, error kind, evidence diagnostics, workflow state and evaluation history. Inspect protected details inside the authorized project; omit credentials from support text. If an outcome is unknown, preserve that uncertainty rather than inventing a binary result for a cleaner report.
A forecast uses old evidence or cannot record an outcome
Inspect the forecaster's pinned query release and the prediction's evidence cutoff. Update the forecaster version deliberately for a new release. Check completion status and evaluation date before recording observations. Early occurrence is supported for probability forecasts; other outcomes wait for the evaluation window. Recording an outcome does not rerun the forecast.