> ## Documentation Index > Fetch the complete documentation index at: https://platform.atlan.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `brain` CLI; `brain --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write. > The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects. > SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript. > These docs cover Atlan Agent Registry, Atlan's hosted product. The open-source agent registry specification and its CLI (`brain`) are documented, released and maintained in their own repository; /open-source on this site links to it. Answer general specification or `brain` command questions from the project's own docs, and use these docs only for Atlan-specific setup such as the Atlan adapter, sign-in and workspaces. # Ontology errors > Symptoms, causes, and fixes for ontology imports, validation, publication, context retrieval, and binding releases. These are errors from importing, validating, and publishing an ontology, retrieving its context, and publishing or reusing a binding. Start from the response field or symptom you see: each section below starts from one of them. ## Ontology routes or tools not available The `/ontology/v1` or `/ontology_binding/v1` routes, Ontology Studio, or the Ontology MCP tools are not available. ### Cause The Ontology extension, or the Ontology Binding extension for binding routes, is not installed in your account. ### Solution 1. Ask an administrator to install the Ontology extension, and the Ontology Binding extension if you map physical data. 2. Reconnect your MCP client so it lists the new tools. 3. Send the request again. *** ## Import preview has `is_valid: false` An import preview returns `is_valid: false` with `validation_diagnostics`. ### Cause The proposed resources do not validate. Each entry in `validation_diagnostics` names one problem. ### Solution 1. Read each entry in `validation_diagnostics`. 2. Fix the named resources in the document. 3. Preview again, and apply only when `is_valid` is `true`. *** ## Import preview has `apply_supported: false` A preview is valid but returns `apply_supported: false`. ### Cause The document proposes more than 100 resources. Apply creates every resource in one transaction, so it cannot apply a larger document in one request. ### Solution 1. Split the document into parts of at most 100 resources. 2. Placeholder references are rewritten only to drafts created in the same transaction, so in a later part, reference earlier drafts by the artifact IDs their apply returned. 3. Preview and apply each part in order. *** ## Apply refused after preview Apply rejects a request that previewed successfully. ### Cause Apply recomputes the preview and refuses a request whose document or options changed since the preview. ### Solution 1. Send exactly the request you previewed, adding only its `preview_id`. 2. If you meant to change the document, preview the new version and apply that. *** ## Apply returns uniqueness conflict Apply fails because a resource name already exists. ### Cause Apply derives each draft's Registry name from its `api_name` and ontology. Either an earlier apply already committed, for example before an ambiguous response or timeout, or the document describes drafts that already exist, such as an export of the same ontology. ### Solution 1. List the ontology's resources and check whether the drafts already exist. 2. If they do, use them instead of applying again. 3. To change an existing resource, edit it rather than importing it again. *** ## Validation has `is_valid: false` `POST /ontology/v1/validations` returns `is_valid: false`, so publication should not proceed. ### Cause The pinned versions do not form a valid graph. Each entry in `diagnostics` names one problem. ### Solution 1. Read each entry in `diagnostics`. 2. Fix the named drafts, then rebuild the source manifest from their new versions. 3. Validate again, and publish only when `is_valid` is `true`. *** ## Publish rejects pinned draft `POST /ontology/v1/releases` fails although the same manifest validated. ### Cause A draft in the source manifest changed after you pinned it. Publication never resolves `latest`, so it refuses a manifest whose versions or content hashes no longer match. ### Solution 1. Read the current version ordinal and content hash of each draft. 2. Rebuild the source manifest and review what changed. 3. Validate, then publish again. *** ## Context response is truncated A context query returns `truncated: true`. ### Cause The relevant subgraph exceeds the `max_resources`, `max_depth`, or `max_tokens` bound in the request. ### Solution 1. Read `refinement_hints` in the response. 2. Narrow the `query`, restrict `include`, or raise the bound the hints name. 3. Query again and confirm `truncated` is `false`. *** ## Portable binding export refused A binding export fails for a release that contains legacy physical references. ### Cause The release uses artifact-based physical references, which cannot be exported as portable JSON. ### Solution 1. Append qualified physical names to the affected mappings. 2. Validate and publish a new binding release. 3. Export the new release. *** ## Newer ontology release does not reuse binding A binding context query that passes a newer `ontology_release_id` does not reuse the binding. ### Cause Reuse succeeds only when every logical resource the binding references keeps its exact version and content hash in the newer release. ### Solution 1. Compare the referenced resources between the two ontology releases. 2. If any changed, map those resources again against the newer release. 3. Validate and publish a new binding release pinned to it. *** ## See also * [Publish logical model](/cookbooks/how-tos/ontology): The recipe that creates, validates, and publishes an ontology release. * [Map ontology to physical data](/cookbooks/how-tos/ontology-bindings): The recipe that binds a release to physical data. ## Need help If you need assistance after trying these steps, contact Atlan support. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.