# Troubleshooting

Read refusals and recorded evidence without losing the failure to a reflex restart.

Read the named failure, active configuration and run handles first. Build identity, readiness, workflow status and worker service are different facts. Keep the evidence that explains the failure.

## The command cannot connect

Read local status and the endpoint you passed. The HTTP console address and gRPC client endpoint are different listeners. Check gRPC connectivity through a client operation.

For a local authoring failure, read the file, line and column in its diagnostic.

## The run stays Running

Describe the concrete run. Read its step, unserved work, current worker and history head. It may be waiting on a signal or timer, paused, awaiting a compatible worker or held by queue policy.

Read connected workers and managed desired/actual state separately. Deployment records describe intended processes. Connected-worker reads show current registrations.

## Check passes but deploy refuses

Emit direct bytecode locally. Bytecode compilation applies checks after typechecking. A deploy refusal can also name disabled deployment, missing authority, archive bounds or conflicting runtime state.

A batch may have deployed earlier entries before a server-side refusal. Read the full batch report before repeating it.

## The query says not found

Confirm the namespace, workflow id and run generation. Read history for terminal workflows. Query a workloop report while its iteration is executing.

## A reconnect loses the stream

Use the correct stream cursor. Per-workflow history, transcript storage and cluster topology each have their own sequence space. Filtered and firehose streams are live-only.

## A package cannot reopen

Read the pinned package version on the run. A missing or invalid archive can leave that run unrecoverable even while other workflows serve. Preserve or redeploy the exact required archive and read the new result.

## Ask for help with evidence

Keep the command's error, source revision, effective config path, namespace and exact run handles. Remove credentials before sharing logs. Do not replace that evidence with a server restart or a broad permission change.