Ontology errors

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: The recipe that creates, validates, and publishes an ontology release.
• Map ontology to physical data: The recipe that binds a release to physical data.

​

Need help

If you need assistance after trying these steps, contact Atlan support.