Agent and workflow troubleshooting

Agent and workflow problems often look similar in the UI but originate in different contracts: registry status, run state, tool execution state, permissions, credentials, approval, persistence, or disabled MCP integration. Diagnose the earliest failed boundary before restarting work.

The guidance avoids unverified builder labels and does not treat scaffolded or disabled surfaces as live execution.

Troubleshooting becomes faster when the failure is classified before remediation begins. Registry and implementation problems prevent run creation; tool-state and permission problems block actions; credential problems belong to secret configuration; approval problems belong to proposals and signed decisions; transition problems belong to the state machine; persistence problems determine what records survive. MCP disabled state is a separate product boundary. Preserving identifiers across those checks allows one change at a time and prevents a generic restart from hiding the real cause.

Configuration errors

Check configuration in dependency order: agent lifecycle and implementation status, tool execution state, permission and scope, required credentials, approval context, transition legality, and persistence availability. Repair the earliest failing contract before retrying. A later symptom—for example a missing output—may only reflect that an earlier tool or approval gate prevented the action from starting.

Use the earliest failed contract as the starting point for a targeted repair.

Registry lifecycle and implementation status should be displayed together during diagnosis. published plus not_started means the product definition exists while execution is unavailable. draft plus active may indicate working code that is not approved for general use. Neither field should be silently used as a substitute for the other.

A run cannot start when the agent slug is missing from the registry or the implementation is not_started. A stub implementation, planned connector, or contract-only tool is not repaired by changing run input. Verify registry lifecycle, implementation status, tool execution state, allowed agent and workspace scope, model readiness, and persistence.

If the definition uses demo fixtures, confirm that the current result is not being mistaken for a live connector or external operation.

A missing registry entry or not_started implementation prevents run creation.

A stub, planned connector, or contract-only tool should not be treated as active.

Verify agent slug, lifecycle, implementation state, workspace scope, model readiness, and persistence mode.

Configuration errors should be checked against registry presence, lifecycle, implementation status, workspace scope, model readiness, and persistence. A planned, stub, or not-started entry cannot be repaired by repeatedly creating runs.

Awaiting-approval and partially-approved are explicit states, but general Approvals card decisions are scaffolded. Local-file, memory-only, or unavailable persistence changes what survives a process or environment change.

Failed, rejected, canceled, expired, paused, recovering, and waiting states require different responses.

A stub, planned connector, or contract-only tool is not executable.

Tool errors

If an action produced partial output before failure, determine whether that output represents an external side effect, user-content change, or read-only result. The next step may be review or rollback by an authorized operator rather than an automatic retry. The tool contract and action record should make that distinction visible.

Check the tool’s execution state before permission or retry behavior. planned and contract_only are non-executable. For an available tool, inspect permission mode, risk, approval requirement, provider, allowed agents, workspace archetypes, credentials, action status, and redacted output.

A blocked action differs from an action awaiting approval. External, destructive, privileged, or user-content writes should not be repeated until it is clear whether the first attempt produced a side effect.

Check tool execution state, allowed agents, workspace archetypes, risk, read-only flag, permission mode, provider, and approval requirement.

A blocked decision differs from an unavailable implementation or failed execution.

Keep tool input and output summaries with the action record for diagnosis.

Tool errors require the complete contract: execution state, agent and workspace allow-lists, provider, risk, read-only flag, permission mode, credentials, and approval requirement. Blocked, unavailable, and failed are different outcomes.

Credentials belong in verified secret paths rather than run inputs or support logs. Check the exact error code and HTTP or run state, then change only the dependency associated with that layer first.

A missing registry entry or not-started implementation prevents run creation.

Credential errors

Keep Ethen Gateway keys, provider BYOK credentials, and tool or connector credentials separate. A missing credential belongs to the provider or tool that needs it; changing the agent slug or approval decision does not create the secret. Never place credentials in instructions, ordinary run input, evidence, screenshots, or support notes.

Use redacted provider, tool, project, run, and action identifiers when diagnosing credential configuration.

Credentials can belong to a provider, connector, or execution environment and should not be placed in run inputs.

A missing credential is not repaired by changing the model instruction.

Resolve the credential through its verified secret path and retest with a bounded action.

Credential errors belong to verified secret paths. Changing prompts or placing a key in run input does not fix missing provider or connector configuration and can expose the secret in logs or evidence.

Use the transition log, audit event, and persistence mode to identify the applicable path.

Approval delays

If the proposal context is incomplete, correct the originating action rather than attempting to approve an ambiguous request.

Inspect the exact state: awaiting_approval, partially_approved, and waiting_for_user require different responses. Confirm that the proposal has parameters, risk, evidence or metadata context, and a signed decision where applicable. The general Approvals page is Private Alpha and its card actions are scaffolded, so clicking a placeholder must not be expected to persist a runtime decision.

Universal reminders, escalation timers, and reviewer reassignment are not specified. Leave the action waiting or blocked according to the authoritative run record.

Awaiting approval and partially approved are explicit run states.

Confirm that the proposal includes the action, parameters, risk, and evidence and that the decision originates from the verified agent-run approval path.

The general Approvals card actions are scaffolded and cannot be assumed to persist.

Approval delays should be read from the run state and proposal records. Confirm that the decision path is the signed agent-run service, because the general Approvals card actions are scaffolded and may not persist.

Rejected work should follow the declared transition rather than being described as a failed provider or tool call.

The approval handling contract includes the fact that a stub, planned connector, or contract-only tool is not executable. Inspect the audit event, persistence mode, and registry, not from a route name, a visible card, or a type definition by itself.

Presentation controls should never be documented as execution gates unless they write the authoritative decision record.

Run failures

A failed terminal state should be investigated from its preceding transition and action result. Retrying without correcting the recorded cause can create another failure while obscuring the original chronology.

When history is incomplete, record the detected persistence mode before drawing conclusions. memory_only can lose records after a process restart, local_file may be tied to one environment, unavailable cannot promise storage, and durable depends on the configured service. Missing records therefore require storage-context review, not an assumed retention event.

If a new run is created after failure, link it to the original through the available parent, idempotency, or support context instead of overwriting the failed record. Keeping both histories preserves the reason for recovery and prevents a later success from erasing evidence of the earlier boundary.

A run in recovering should be inspected through its transition history and recovery records rather than restarted as though it were failed. A run in expired is terminal, while waiting_for_user remains active but cannot continue without input. These distinctions determine whether the next action is review, input, a new run, or an implementation fix.

Use the transition log to identify the state before failure and whether the requested transition was allowed. Terminal states—completed, failed, rejected, canceled, and expired—cannot transition again. paused and recovering are nonterminal and should not be treated as completed.

Check idempotency and parent-child relationships before creating another run. Then inspect actions, proposals, decisions, evidence, output, audit events, and persistence mode. Memory-only or unavailable persistence can explain missing history after a process change.

Inspect invalid transitions, terminal state, failing action, evidence, transition logs, audit events, child runs, output, and persistence mode.

Local-file, memory-only, or unavailable persistence can change what survives a process or environment change.

Run failures need state-specific handling. Failed, rejected, canceled, expired, paused, recovering, waiting for user, and approval states should not be reduced to one restart instruction, especially when persistence is local-file, memory-only, or unavailable.

A final state narrows the next action. failed points to execution or transition error, rejected to an approval decision, canceled to explicit termination, and expired to lifecycle expiry. None can be reopened directly. Recovery should create or use a supported path while retaining the original run’s chronology and side-effect history.

Debugging checklist

Do not merge records from different environments or persistence modes into one timeline. Confirm the project, agent slug, run ID, and storage context first.

Keep demo and fixture records out of a live incident timeline unless they are explicitly identified. Mixing them with active run records can make a planned or simulated capability appear to have executed and can obscure the persistence mode of the real run.

Change one boundary at a time. First correct registry or implementation state, then tool availability and permissions, then credentials, then approval context, then the requested transition. Recreating the run after every change can conceal whether idempotency returned an existing record or whether memory-only persistence lost the previous history.

For a support investigation, provide the run ID, action ID, current and prior states, tool ID, proposal or decision ID, persistence mode, and redacted error details. Exclude credentials and unnecessary user content.

Confirm registry and implementation state, then validate trigger, inputs, idempotency, state transition, tool contract, permission, credential, approval, and persistence.

Check whether the problem belongs to a disabled MCP path rather than an agent runtime failure.

Escalate with run, action, proposal, transition, and evidence identifiers without including secrets.

A disciplined debug pass preserves run, action, proposal, transition, evidence, and audit identifiers; checks MCP disabled state when relevant; changes one dependency; and reruns only after the observed cause has been corrected.

Remediation must remain tied to verified runtime and surface behavior; disabled MCP, scaffolded approvals, and environment-dependent persistence cannot be repaired through invented controls.

Separate failures by ownership. Registry and implementation errors occur before a run can start. Tool errors require the tool ID, execution state, permission mode, risk, approval requirement, action status, and redacted error. Credential problems belong to the integration or provider path and should not be copied into run inputs. Approval delays require the proposal, evidence, current state, and a verified signed-decision path rather than the scaffolded general queue.

For run failures, read the transition log before attempting recovery. Terminal states cannot be reopened, while paused and recovering are nonterminal and may have supported next transitions. Check idempotency and prior side effects before replay, then confirm whether history is durable, local-file private-beta, memory-only, or unavailable. MCP’s empty disabled state is expected and should not be “fixed” by spawning a process or calling an unverified server route.