Troubleshooting

Troubleshoot from evidence before changing configuration. Each issue should be recorded using the same pattern:

1. Symptom — what the user can see.
2. What it means — the narrowest supported interpretation.
3. What to check — the authoritative surface or command.
4. Resolution — the smallest justified action.
5. Evidence to expect — what confirms recovery.

Onboarding cannot continue

Symptom: Save & continue is unavailable or setup cannot resolve a model.

What it means: the draft provider/model selection is incomplete, or the saved choice did not resolve as both configured and effective.

What to check: for Ollama, open Models and look for at least one installed model with provider-confirmed completion capability. Check the endpoint and credential in Settings → Providers.

Resolution: explicitly install or select an eligible model, or correct the provider settings. Onboarding does not install a model or invent a fallback.

Evidence to expect: AI Runtime saves successfully and the Verify step can run its separate provider check.

Ollama is unavailable

Symptom: LLM Offline, provider checks fail, or local model inventory is unavailable.

What it means: Pioneer could not currently reach the configured Ollama endpoint. It does not prove that configuration was lost.

What to check:

Invoke-RestMethod -Uri "http://127.0.0.1:11434/api/version"

Resolution: Start the Windows Ollama application if no process is serving. If ollama serve says the address is already in use, repeat the version check; a successful response means another Ollama process already owns the port.

Evidence to expect: the version request returns a version, Models can complete its provider check, and Machine observes Ollama as reachable.

A configured model is unavailable

Symptom: the default model is shown as configured but not effective, or it cannot be selected for Chat.

What it means: durable intent remains, but current provider evidence does not show a generation-capable model that satisfies the configured name.

What to check: open Models and compare configured, effective, installed, and Chat-selectable states. For Ollama, verify inventory with ollama list.

Resolution: explicitly install the intended model, or choose an observed Chat-selectable model and separately set it as the default.

Evidence to expect: the model appears in observed installed inventory, its capability includes completion, and configured/effective state agrees.

No local models can be selected for Chat

Symptom: onboarding or Chat shows no eligible Ollama choices.

What it means: no currently observed installed model has provider-confirmed completion capability. Embedding-only and capability-unknown models are excluded.

What to check: inspect each model's capability evidence in Models and confirm provider reachability.

Resolution: retry the provider check if observation failed, or explicitly install a completion-capable model. Onboarding never downloads one automatically.

Evidence to expect: at least one installed model is labeled Chat-selectable and appears in the picker.

The backend is not reachable

Symptom: the top bar shows Backend Offline or Machine cannot load.

What it means: the frontend cannot reach the Pioneer API at its configured base URL.

What to check:

Invoke-RestMethod -Uri "http://127.0.0.1:8420/health" |
    ConvertTo-Json -Depth 5

Also inspect the backend terminal. A browser refresh cannot load changed Python code into a backend that was started without reload.

Resolution: start or restart the backend with the command in Starting Pioneer. Confirm that another process is not unexpectedly using port 8420.

Evidence to expect: /health reports status: ok and the top bar changes to Backend Online. llm_available is a separate provider observation.

Flow validation fails

Symptom: Canvas reports that the draft is invalid and the Flow cannot run.

What it means: current topology or block configuration does not satisfy the Flow contract. No execution has occurred.

What to check: inspect the named block and validation issue on Canvas. Check missing required configuration, incompatible or disconnected ports, and whether the draft differs from its saved Flow.

Resolution: correct the specific draft configuration or connection, then validate again. Save and run remain separate actions.

Evidence to expect: Canvas reports a valid draft. Only a later explicit run can produce execution evidence.

A repair proposal is stale

Symptom: draft or saved apply reports that the target changed.

What it means: the current fingerprint, or Saved Flow revision and fingerprint, no longer matches the proposal that was reviewed.

What to check: inspect the current target in Canvas or ask Chat to inspect the specific Saved Flow again.

Resolution: discard the old proposal, diagnose the current state, generate a new guarded proposal, and review it. Pioneer does not auto-rebase.

Evidence to expect: the new proposal names current guards; an approved apply either changes that exact target or returns another zero-write stale result.

Saved Flow apply conflicts

Symptom: an approved saved apply reports a compare-and-swap conflict or no write.

What it means: another change won the revision guard, or the proposed change became a semantic no-op.

What to check: current Saved Flow revision, fingerprint, and definition.

Resolution: do not retry the old mutation blindly. Reinspect and propose against the current revision.

Evidence to expect: a successful apply reports a new revision and persisted state; a no-op truthfully reports no semantic change.

An approval was rejected or cancelled

Symptom: apply, run, or Script work did not proceed after an approval card.

What it means: the scoped decision was denied, cancelled, expired, or the target became stale. It does not imply that an earlier or different boundary was denied.

What to check: approval request and decision evidence in Chat, Executions, or Sessions, including request identity and target.

Resolution: inspect current state before issuing a new explicit request. Do not assume a prior approval can be reused.

Evidence to expect: a new request has a new scoped approval and a separate execution/apply outcome.

A run failed

Symptom: Executions shows Failed.

What it means: one block or the job recorded a terminal failure. It does not identify the cause by itself.

What to check: select the run and read the failure anchor, stage timeline, row transitions, output bounds, and approvals. Copy the explicit run ID.

Resolution: ask Chat to diagnose that run, review the evidence and inference, then use the explicit repair workflow if a change is justified.

Evidence to expect: a diagnosis cites authoritative run evidence; any repair, rerun, and verification each has its own result.

A run was cancelled or timed out

Symptom: an operation reports cancellation/timeout, or a Script failure contains timeout metadata.

What it means: the recorded operation did not complete normally. Pioneer does not claim that all external effects were rolled back or that the run can be resumed after restart.

What to check: exact run and block evidence, timeout metadata, cancellation state, and any external system involved.

Resolution: verify current external state first. Correct the timeout or task scope, then issue a new explicit run if appropriate.

Evidence to expect: the new run has a different run ID and its own lifecycle.

Machine telemetry is unavailable

Symptom: a field says Unavailable, Machine is disconnected, or a prior sample is stale.

What it means: the platform did not report that optional field, or the most recent metrics request failed. Unavailable is not zero.

What to check: backend health, the Machine refresh result, sample ID, and whether the hardware/runtime supports the metric.

Resolution: restore backend connectivity and refresh. Do not install an unrelated telemetry system merely to fill an optional field.

Evidence to expect: a new sample timestamp/ID or an honest continuing Unavailable value.

The in-product documentation is missing

Symptom: Docs shows that the documentation build is unavailable.

What it means: the generated build/docs/ artifact is absent from the backend's resolved documentation directory.

What to check: from the repository root, run:

.\scripts\docs.ps1 build

Resolution: fix any strict build/validation error, then choose Retry in Docs or refresh the panel.

Evidence to expect: /api/docs/status reports available and the searchable manual loads under /docs/.

The wrong profile appears active

Symptom: expected sessions, Memory, or Saved Flows are absent.

What it means: Pioneer may be using a different durable home; this is not yet evidence of deletion.

What to check: Machine profile ID, resolved home, and source; then inspect PIONEER_HOME in the backend terminal.

Resolution: stop the backend, set the intended home, start a new backend process, and verify Machine before making changes.

Evidence to expect: the intended stable profile identity and its durable records return.

Escalating an unresolved issue

Capture the active profile ID and Pioneer home from Machine, the exact symptom and time, relevant run or session IDs, and bounded evidence from Executions or Logs. Do not include provider credentials or unreviewed row payloads.