## Atlan MCP errors

URL: https://docs.atlan.com/product/capabilities/atlan-ai/references/mcp-errors

> 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:

```json
{
 "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?

- **`false`** means the call is wrong, not unlucky. Retrying it unchanged fails the same way. Follow `guidance` and change the call.
- **`true`** means 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. |

> **Note**
>
> 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.

## See also

- [MCP tools](https://docs.atlan.com/llms/platform/atlan-mcp-overview/mcp-tools/llms.txt): every tool the Atlan MCP server exposes, with its category and access level.
- [Security](https://docs.atlan.com/llms/platform/atlan-mcp-overview/mcp-security/llms.txt): how Atlan MCP authenticates callers and protects tenant data.

_Last updated: 17 September 2026._

---

> **AI agent?** Install the Atlan Docs MCP for direct access: https://docs.atlan.com/skills/install-docs-mcp.md