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

# Troubleshooting

Diagnose common B3OS workflow, trigger, connector, wallet, API, and execution hook issues.

Use this page when a workflow fails validation, does not trigger, pauses unexpectedly, cannot call a provider, or delivers unexpected results.

## Workflow Will Not Publish

| Symptom                  | Check                                                                        |
| ------------------------ | ---------------------------------------------------------------------------- |
| Missing required fields  | Open each node with a validation error and compare against its action schema |
| Broken expression        | Confirm referenced node IDs, trigger fields, props, and loop variables exist |
| Missing connector        | Select or create the required connector type                                 |
| Unsupported wallet chain | Confirm the action supports the selected chain and wallet                    |
| Invalid graph            | Check branches, loops, child nodes, and unreachable nodes                    |

## Workflow Does Not Trigger

| Trigger type            | Check                                                                           |
| ----------------------- | ------------------------------------------------------------------------------- |
| Manual                  | Confirm the workflow has a live version or valid draft test input               |
| Schedule or cron        | Confirm the workflow is active, not paused, and schedule config is valid        |
| Webhook                 | Confirm URL/secret, method, content type, and payload shape                     |
| EVM log                 | Confirm chain, address, topics, deployment block, and listener state            |
| Slack or SaaS           | Confirm connector health, provider permissions, event subscription, and filters |
| Payment or market event | Confirm provider account, event type, and filter criteria                       |

## Node Fails at Runtime

1. Open the run and find the first failed execution.
2. Inspect the resolved node input.
3. Compare the input to the action schema.
4. Check connector or wallet requirements.
5. Inspect sanitized provider error details.
6. Add a format, branch, or code-transform node if incoming data needs normalization.

**Start with resolved input**

The most useful debugging view is usually the node input after expression resolution. It shows what the action
  actually received.

## Connector Errors

| Error type      | Likely cause                                            |
| --------------- | ------------------------------------------------------- |
| Unauthorized    | Token expired, provider account revoked, missing scope  |
| Forbidden       | Provider account lacks resource access                  |
| Not found       | Channel, shop, sheet, customer, or resource ID is wrong |
| Rate limited    | Provider throttling or too many workflow runs           |
| Invalid payload | Action schema or provider API expectation changed       |

## Wallet Errors

| Error type           | Likely cause                                                                     |
| -------------------- | -------------------------------------------------------------------------------- |
| Insufficient funds   | Missing token balance or native gas token                                        |
| Reverted transaction | Contract condition failed, slippage, allowance, deadline, or chain state changed |
| Bad address          | Invalid destination, wrong chain, or malformed token address                     |
| Nonce conflict       | Concurrent wallet activity or stale pending transaction                          |
| Missing wallet       | Permission, setup, or unsupported action configuration                           |

## Execution Hook Issues

| Symptom                | Check                                                        |
| ---------------------- | ------------------------------------------------------------ |
| No delivery            | Hook enabled, event type selected, destination URL reachable |
| Signature failure      | Correct secret and canonical payload handling                |
| Repeated retries       | Endpoint non-2xx responses or timeout                        |
| Duplicate side effects | Missing idempotency in your receiver                         |
| Missing fields         | Receiver assumes optional fields are always present          |

## When to Pause a Workflow

Pause a workflow if it repeatedly fails, calls an expensive provider unexpectedly, emits duplicate webhooks, or could perform an unsafe wallet operation. Repair and test a draft before resuming.