Reference for the error envelope returned by Atlan MCP tools—code, category, is_retryable, message, and guidance—plus what each category means and whether retrying can help.
Atlan MCP errors
When an Atlan MCP tool can't complete a call, it returns a structured error instead of a free-text message. Every tool uses the same shape, so your agent or client can tell what went wrong, whether the same call can ever succeed, and what to do next.
Error envelope
A failed tool call returns an object with five fields:
{
"code": "ATLAN-MCP-2001",
"category": "not_found",
"is_retryable": false,
"message": "No asset found for GUID '...'.",
"guidance": [
"Re-search to get a current GUID, then retry."
]
}
| Field | Description |
|---|---|
code | Stable identifier for the specific failure, in the form ATLAN-MCP-NNNN. Safe to match on, log, and quote to Atlan support. |
category | Coarse bucket the failure falls into. Several codes can share one category. |
is_retryable | Whether repeating the same call unchanged can ever succeed. |
message | One-line, sanitized explanation. Never contains internal hostnames, ARNs, service-account identifiers, or raw stack traces. |
guidance | Ordered list of concrete next actions. The first item is the action to take now. |
The first digit of code reflects the category: 1 input, 2 not found, 3 authentication, 4 denied, 5 server, 6 rate limit.
Read is_retryable before retrying
is_retryable answers one question: can this exact call succeed if you send it again?
falsemeans the call is wrong, not unlucky. Retrying it unchanged fails the same way. Followguidanceand change the call.truemeans the failure is transient. Back off and retry.
Blind retries are the most common way agents waste calls on Atlan MCP. A dead GUID, for example, never resolves by retrying—it resolves by searching for the asset again and using the GUID from the result. That's why the recovery action is in guidance[0].
Categories
| Category | Typical cause | Retry helps? |
|---|---|---|
invalid_input | Validation failure, malformed argument, or bad SQL | No—fix the call |
not_found | The referenced asset, tag, domain, or dataset doesn't exist | No—re-resolve the reference |
auth_required | Session or token expired | No—re-authenticate, then retry |
access_denied | Caller lacks permission for this action | No |
upstream_denied | Governance rules or credentials on a backend blocked the call | No |
conflict | The object already exists | No—fetch or rename instead |
rate_limited | Too many calls in a short window | Yes—back off |
server_error | Unexpected backend failure or timeout | Yes |
module_disabled | The tool's module isn't enabled for your tenant | No—contact your Atlan admin |
Common codes
| Code | Category | Meaning and first action |
|---|---|---|
ATLAN-MCP-1001 | invalid_input | The value isn't a 36-character asset GUID. Search for the asset, then pass the guid from the result. |
ATLAN-MCP-1006 | invalid_input | A qualifiedName was passed where a GUID is required. Resolve it to a GUID first—the two aren't interchangeable. |
ATLAN-MCP-1003 | invalid_input | A write statement was sent to a read-only tool. Only SELECT, WITH, SHOW, DESCRIBE, and EXPLAIN are permitted. |
ATLAN-MCP-1005 | invalid_input | The search paged too deep. Narrow it with filters instead of paginating further. |
ATLAN-MCP-1010 | invalid_input | The request was rejected as too large before reaching Atlan. Split it into smaller batches. |
ATLAN-MCP-2001 | not_found | No asset matches the GUID. Re-search for a current GUID. |
ATLAN-MCP-3001 | auth_required | The session expired. Re-authenticate, then retry. |
ATLAN-MCP-4001 | access_denied | You aren't authorized for this action. |
ATLAN-MCP-4003 | conflict | The object already exists. Fetch the existing object or choose a different name—don't retry the create. |
ATLAN-MCP-6001 | rate_limited | Too many calls. Back off and retry. |
Conflicts on create tools return ATLAN-MCP-4003 with category conflict. Earlier versions reported these as an input validation failure, which pointed callers toward retrying a call that can never succeed.
Empty results aren't errors
A tool that runs successfully but finds nothing returns a normal result, not an error envelope. Such a result may still carry a guidance field suggesting a different approach—for example, querying lineage in the opposite direction. Treat that as a hint, not a failure.