Troubleshooting: Agent Studio graph and custom-tool validation

The Agent Studio canvas (see Build Agents Visually in the Agent Studio Canvas) can reject a publish or a test-run, and the custom-tool registry rejects registration or invocation, each with its own validation code. The runtime-error family (agent runtime errors) covers the codes that fire mid-turn; this page owns the validation family that fires at publish, register, or wiring time, and — in Custom tool runtime failures — the dispatch family that fires later, when a registered executor misbehaves mid-call. Every failure here arrives as a structured envelope — key on error.code, and for GRAPH_VALIDATION_FAILED read the per-issue list in error.details before you touch the canvas:

{
  "error": {
    "code": "GRAPH_VALIDATION_FAILED",
    "message": "Graph failed publish validation",
    "status": 422,
    "details": [
      "edge 7f2e1a source references missing node 'node_4'",
      "node 'collect_digits' has no outgoing edge",
      "play_prompt node 'welcome' has empty spoken text"
    ]
  },
  "meta": {
    "request_id": "req_01J04Q8K2N",
    "timestamp": "2026-09-19T10:02:14.410Z"
  }
}

Graph publish validation

Code	HTTP	Cause	Fix
`GRAPH_VALIDATION_FAILED`	422	The graph failed either structure validation (an edge pointing at a missing node, an empty node id, an unrecognised node kind) or publish-time semantic validation.	Read `error.details` — it lists one entry per failing node or edge. Fix each named node on the canvas, Save, and Deploy again. The console renders the `details` list inline on publish, so you do not have to guess which node is wrong.
`GRAPH_TOOL_NODES_NOT_SUPPORTED_IN_TEST_RUN`	422	A Tool Call node sits in the graph and the test-run endpoint was asked to execute it. Tool nodes dispatch through the MCP registry, which only the published agent’s `/run` path wires.	Publish the graph, then invoke the agent’s `/run` endpoint instead of the Studio test-run for a tool-node check. The response `meta` message lists the offending tool node ids.

Custom tool registration

These codes come from POST /agents/custom-tools and the invoke path (see Build custom tools for AI agents).

Code	HTTP	Cause	Fix
`RESERVED_TOOL_NAME`	422	The requested tool name collides with a built-in platform tool (like `lookup_contacts` or `send_sms`).	Rename the tool to a tenant-specific slug and re-register. Names are immutable once set, so pick the slug before any agent trains prompts on it.
`TOOL_NAME_TAKEN`	409	Another custom tool in the tenant already holds the requested name. The registry is tenant-wide — one tool per name.	List the existing tool (`GET /agents/custom-tools`) and either rename-or-retire it, or PATCH the existing registration instead of re-creating.
`TOOL_DISABLED`	409	The invoke request named a tool whose `enabled` flag is off. Per-agent attach lists still name the id; the runtime skips it when the flag is off.	Re-enable the registry entry, then retry the invoke. Unlike versions, `enabled` is the only gate — flipping it back on resumes invocation immediately.
`INVALID_EXECUTOR_URL`	422	The `executor_url` failed the SSRF write-time guard — the same public-FQDN check webhook and MCP registrations enforce. Rejected classes: non-HTTPS scheme, loopback or private address, link-local or cloud-metadata host, internal-only hostname suffix, and DNS records that resolve internally.	Point the executor at a public HTTPS FQDN. The `failure_code` field on the envelope names the reject class.

Sample INVALID_EXECUTOR_URL envelope:

{
  "error": {
    "code": "INVALID_EXECUTOR_URL",
    "message": "Executor URL rejected: resolves to a private address",
    "failure_code": "private-address",
    "status": 422
  },
  "meta": {
    "request_id": "req_01J04R1V6X",
    "timestamp": "2026-09-19T10:04:52.018Z"
  }
}

Tool wiring errors

These fire when a graph, registry, or agent reference points at a KB, a handoff target, or a runtime handler that cannot resolve.

Code	HTTP	Cause	Fix
`TOOL_IMPL_NOT_REGISTERED`	500	The Orby runtime listed a tool by name but no handler was registered for it — a runtime wiring fault, not a tenant mistake.	Escalate with the `request_id` from `meta`; support can trace which registry entry the executor resolved.
`INVALID_HANDOFF_TARGETS`	422	The `handoff_targets` list on an agent names agents that do not exist in the tenant.	The message lists the bad ids. Remove the stale agents or correct the ids, then re-submit.
`INVALID_KNOWLEDGE_BASE_IDS`	422	`knowledge_base_ids` names KBs that do not resolve in this tenant — usually a stale id pasted from another agent or a knackered KB row.	The message lists the bad ids. Replace them with live KB ids, then re-submit.

Custom tool runtime failures

Registration proves your executor URL is reachable and public; dispatch is where production reality shows up. When the agent invokes a registered custom tool (or when you fire the tool’s test endpoint), the platform dispatches a signed POST to your executor_url and classifies whatever comes back into one of five codes. Unlike the 422s above, these are not publish-time gates: they fire per call, against a live executor.

The dispatch contract

Per-tool dispatch timeout. Every tool carries a timeout_ms (1,000 to 60,000, default 30,000). One dispatch that overruns it ends the attempt; if the tool configures a retry policy, each retry attempt gets its own timeout, and the whole sequence is capped by the agent execution budget.
Response cap. A response body is capped at 1 MiB; a larger body is cut off mid-stream and the attempt fails.
Who owns what. A 4xx or 5xx status, a slow response, or a broken TLS chain is your executor’s fault. A dispatch fault that happens before your executor is even reached is the platform’s side. The table below assigns each code to a side.

This mirrors the MCP surface (see Bring your own MCP servers): there, discovery carries an 8-second tools/list handshake timeout and each tools/call is bounded by the same per-tool timeout_ms (default 30 s). The HTTP custom-tool surface skips the discovery step, so the per-tool dispatch window is the only clock.

Decoding the codes

Code	Executor status	Who owns the fault	Fix
`CUSTOM_TOOL_TIMEOUT`	No response inside `timeout_ms` (default 30 s)	Executor	Your handler overran the dispatch window. Move long work behind the call: accept the request, return a job id, and expose a second tool that polls for the result; or raise `timeout_ms` (max 60,000) if the work is genuinely that long. Check `duration_ms` in the attempt history: a value near `timeout_ms` means the executor is simply slow, not dead.
`CUSTOM_TOOL_NETWORK_ERROR`	Never reached	Executor	DNS failure, refused connection, or a TLS fault on the executor side: untrusted chain (`UNABLE_TO_VERIFY_LEAF_SIGNATURE`), expired certificate (`CERT_HAS_EXPIRED`), hostname mismatch, or a rotated certificate your trust chain no
longer pins. The registration-time SSRF guard proves the URL is public and HTTPS; it does not prove the certificate is valid at dispatch. Fix the executor’s DNS record, listener, or certificate.
`CUSTOM_TOOL_SERVER_ERROR`	`5xx`	Executor	Your executor crashed or errored mid-request. Read its logs for the matching timestamp; a retry only helps if the crash is transient.
`CUSTOM_TOOL_CLIENT_ERROR`	`4xx`	Executor	Your executor rejected the request: bad signature under your `executor_secret`, a changed request shape, or a routing miss in your service. This is deterministic; a retry returns the same 4xx. Fix the executor and re-test from the tool’s test endpoint before re-enabling.
`CUSTOM_TOOL_DISPATCH_FAILED`	n/a, platform-side	Platform	The dispatch layer itself faulted (dispatcher non-2xx, or an unreadable or unrecognisable dispatch envelope) before or around your executor. Retry is safe per Idempotency and safe retries; if it persists, escalate with the `request_id` from `meta`.

Every dispatch failure result carries error_code — one of the five codes — and a sanitized error line that never leaks the raw executor or network exception. Where the tool configures a retry policy, the recorded attempt history keeps one entry per attempt with its own status, duration_ms, and raw error, and the surfaced code is the terminal outcome after retries.

What to capture

meta.request_id from the envelope.
The tool name and the tenant.
duration_ms per attempt: near timeout_ms says slow executor; near-zero says DNS or connection refused; a platform-side error string on a fast attempt says dispatch fault.
The executor’s own status code from the attempt row, and your executor’s logs at the same timestamp.

What NOT to do

Do not blind-retry CUSTOM_TOOL_CLIENT_ERROR. A 4xx is your executor deterministically rejecting the request; a loop only burns your retry budget.
Do not loop on CUSTOM_TOOL_SERVER_ERROR either. A crashing executor keeps crashing; fix the executor first, then retry.
Do not raise timeout_ms to hide a slow executor. The ceiling is 60,000 and the agent execution budget still caps the whole turn; a tool that needs minutes wants the async job-id pattern, not a bigger window.
Do not treat CUSTOM_TOOL_NETWORK_ERROR as a platform outage. TLS and DNS faults on a public HTTPS URL are executor-side; the platform pins the resolved address for the dispatch exactly as validated at registration.

When to escalate for runtime codes

Escalate only CUSTOM_TOOL_DISPATCH_FAILED, the platform-side class, with the request_id and the attempt rows. Timeout, network, server, and client classes are executor-side and carry everything you need to fix them yourself.

KB re-chunking

Code	HTTP	Cause	Fix
`LEGACY_KB_DOC_NOT_RECHUNKABLE`	409	The Re-chunk this doc action (or `POST /agents/:id/knowledge-base/:docId/rechunk`) ran against a document uploaded through the legacy knowledge-base flow, which has no rewriteable chunk rows for the modern embeddings model.	Re-upload the document through the canonical KB flow — see Knowledge base document inspector — then re-chunk.

Decision checklist

Run this after any of the codes above:

Read error.code on the envelope.
If it is one of the deterministic 422s (GRAPH_VALIDATION_FAILED, GRAPH_TOOL_NODES_NOT_SUPPORTED_IN_TEST_RUN, RESERVED_TOOL_NAME, INVALID_EXECUTOR_URL-family reject classes, INVALID_HANDOFF_TARGETS, INVALID_KNOWLEDGE_BASE_IDS) — do NOT retry; fix the payload, the graph, or the registry first.
If it is TOOL_NAME_TAKEN or TOOL_DISABLED — clear the collision or re-enable the tool, then retry.
If it is TOOL_IMPL_NOT_REGISTERED — treat as a runtime fault; do not retry and escalate.
For GRAPH_VALIDATION_FAILED, scan error.details for the exact node/edge and fix on the canvas; the console prints the same list inline.
If it is one of the runtime dispatch codes (CUSTOM_TOOL_TIMEOUT, CUSTOM_TOOL_NETWORK_ERROR, CUSTOM_TOOL_SERVER_ERROR, CUSTOM_TOOL_CLIENT_ERROR) — the executor owns the fault; follow Custom tool runtime failures and retry only after the executor changed.
If it is CUSTOM_TOOL_DISPATCH_FAILED — platform side; a bounded retry is safe, then escalate with request_id.

What NOT to do

Do not retry GRAPH_VALIDATION_FAILED in a loop. The graph is invalid; a retry re-runs the same gate.
Do not rename a custom tool to work around TOOL_NAME_TAKEN. The name is the id the LLM sees and every attached agent trains prompts on it; renaming after the fact breaks trained prompts. Rename the duplicate target instead.
Do not point executor_url at an internal host with a public alias. DNS resolution runs at write time and again at dispatch, so a public-looking hostname that resolves internally still fails.
Do not escalate on TOOL_NAME_TAKEN / TOOL_DISABLED / INVALID_HANDOFF_TARGETS / INVALID_KNOWLEDGE_BASE_IDS / the 422 validation codes, or on the four executor-owned dispatch codes. These are deterministic tenant-owned gates. Escalate only TOOL_IMPL_NOT_REGISTERED (500) and CUSTOM_TOOL_DISPATCH_FAILED with request_id.
Do not retry the re-chunk on a legacy document. Re-upload through the canonical KB flow first; the 409 is deterministic.
Do not blind-retry the dispatch family. CUSTOM_TOOL_CLIENT_ERROR and CUSTOM_TOOL_SERVER_ERROR mean your executor rejected or crashed on the request; only CUSTOM_TOOL_DISPATCH_FAILED is safe to retry as-is.

When to escalate

Escalate to support only for TOOL_IMPL_NOT_REGISTERED (500) and CUSTOM_TOOL_DISPATCH_FAILED — the platform-side faults. The request_id from meta lets support trace which registry entry the executor resolved, or which dispatch attempt faulted. Everything else on this page is a deterministic tenant-side fix, including all four executor-owned dispatch codes.

Reference

Troubleshooting: Agent Studio graph and custom-tool validation

Troubleshooting: Agent Studio graph and custom-tool validation

Graph publish validation

Custom tool registration

Tool wiring errors

Custom tool runtime failures

The dispatch contract

Decoding the codes

What to capture

What NOT to do

When to escalate for runtime codes

KB re-chunking

Decision checklist

What NOT to do

When to escalate

See also

​Troubleshooting: Agent Studio graph and custom-tool validation

​Graph publish validation

​Custom tool registration

​Tool wiring errors

​Custom tool runtime failures

​The dispatch contract

​Decoding the codes

​What to capture

​What NOT to do

​When to escalate for runtime codes

​KB re-chunking

​Decision checklist

​What NOT to do

​When to escalate

​See also

Troubleshooting: Agent Studio graph and custom-tool validation

Graph publish validation

Custom tool registration

Tool wiring errors

Custom tool runtime failures

The dispatch contract

Decoding the codes

What to capture

What NOT to do

When to escalate for runtime codes

KB re-chunking

Decision checklist

What NOT to do

When to escalate

See also