> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug your workflows

> Find the node that broke, read the instruction that caused it, and fix it.

An execution failed, or it finished with the wrong answer. Something in the workflow's instruction set is likely wrong.

***

## Ask Astro first

Astro reads an execution faster than you can. Open Astro, type `@`, and pick the execution from the menu.

<Card title="Mention an execution" icon="at-sign" img="/images/astro-mention-executions.png" horizontal>Astro reads the timeline, the screenshots, and the workflow's reasoning.</Card>

Ask it plainly:

* "Why did this execution stop?"
* "What did the workflow do on the login page?"
* "Change the instructions so this does not happen again."

Astro names the node that broke, quotes the reasoning behind it, and edits the workflow. It writes every edit to a draft, so read the change before you publish it. See [Build in the platform](/build/in-the-platform).

<Tip>
  Name the symptom you saw. "It booked the wrong slot" beats "it failed".
</Tip>

***

## Find the problem manually

<Steps>
  <Step title="Watch the recording">
    Open the execution and play the recording. You see the screen the workflow saw.

    Watch for the moment the execution leaves the path you wanted. Note the time.
  </Step>

  <Step title="Find the node">
    The timeline marks every node the execution entered. Find the node that owns the moment you noted.
  </Step>

  <Step title="Read the activity log">
    Inside that node, read what the workflow did and why.
  </Step>

  <Step title="Find the instruction">
    Put the `reasoning` next to that node's instructions in the builder.

    The workflow did what it believed the instructions asked. Find where its belief and your intent part company. That gap is the line to rewrite.

    See [Write good instructions](/build/instructions) for more help on building effective instructions.
  </Step>
</Steps>

<Info>
  A `cancelled` execution carries a reason that names the limit it hit. See [Executions and statuses](/concepts/executions).
</Info>

***

## Debug from your coding agent via MCP/API

You can use coding agents like Claude Code or Codex to debug executions.

<Tabs>
  <Tab title="MCP">
    Connect the [MCP server](/build/from-your-coding-agent), then ask in plain language.

    Ask for something like:

    ```
    Find the last failed execution of workflow <id>, read its activities,
    and tell me which node broke and why.
    ```

    Your coding agent then opens that node and proposes the instruction change.
  </Tab>

  <Tab title="SDK">
    Fetch the timeline, and print the reasoning labelled by node.

    <CodeGroup>
      ```ts TypeScript theme={null}
      import { client, executionsList, executionActivitiesGet } from 'asteroid-odyssey';

      client.setConfig({
        baseUrl: 'https://odyssey.asteroid.ai/agents/v2',
        headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
      });

      const { data: executions } = await executionsList({
        query: { agentId: process.env.ASTEROID_AGENT_ID!, status: ['failed'], pageSize: 1 },
      });

      const failed = executions?.items ?? [];
      if (failed.length === 0) throw new Error('No failed executions to inspect.');

      const executionId = failed[0].id;

      const { data: activities } = await executionActivitiesGet({
        path: { executionId },
        query: { order: 'asc' },
      });

      let node = 'start';
      for (const activity of activities ?? []) {
        const payload = activity.payload;
        if (payload.activityType === 'transitioned_node') node = payload.newNodeName;
        if (payload.activityType === 'reasoning') console.log(`[${node}] ${payload.reasoning}`);
        if (payload.activityType === 'action_failed') console.log(`[${node}] FAILED ${payload.message}`);
      }
      ```

      ```python Python theme={null}
      import os

      from asteroid_odyssey import ApiClient, Configuration
      from asteroid_odyssey.api.execution_api import ExecutionApi

      config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

      with ApiClient(config) as api_client:
          execution_api = ExecutionApi(api_client)

          executions = execution_api.executions_list(
              agent_id=os.environ["ASTEROID_AGENT_ID"],
              status=["failed"],
              page_size=1,
          )
          if not executions.items:
              raise SystemExit("No failed executions to inspect.")

          execution_id = executions.items[0].id

          activities = execution_api.execution_activities_get(
              execution_id=execution_id,
              order="asc",
          )

          node = "start"
          for activity in activities:
              # payload is a union, so read the resolved model off actual_instance
              payload = activity.payload.actual_instance
              if payload.activity_type == "transitioned_node":
                  node = payload.new_node_name
              elif payload.activity_type == "reasoning":
                  print(f"[{node}] {payload.reasoning}")
              elif payload.activity_type == "action_failed":
                  print(f"[{node}] FAILED {payload.message}")
      ```
    </CodeGroup>

    That printout is the workflow's train of thought, labelled by node. The last lines before the failure should guide your workflow to the instruction to rewrite.
  </Tab>
</Tabs>

***

## Next

<CardGroup cols={2}>
  <Card title="Write good instructions" icon="pen-line" href="/build/instructions" horizontal>The shape that survives a real portal</Card>
  <Card title="Improve your workflows" icon="trending-up" href="/operate/improve" horizontal>Make a working workflow faster and cheaper</Card>
  <Card title="Executions and statuses" icon="activity" href="/concepts/executions" horizontal>Every status, and every cancel reason</Card>
  <Card title="Test, iterate, publish" icon="check-check" href="/build/test-and-publish" horizontal>Ship the fix</Card>
</CardGroup>