> ## 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 `aireg` CLI; `aireg --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 AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces.

# Troubleshoot Metrics Studio

> Fix common Metrics Studio problems: import duplicates, blocked saves and releases, unconfirmed writes, and agents that can't find a metric or read an old version.

<Badge color="orange">Preview</Badge>

Find the message or symptom you see, then follow the fix. Quoted text is exactly what Studio shows.

## Import says "Name already used"

**Cause:** A metric with that identifier already exists in the destination workspace. Archived metrics count too, because their names stay reserved.

**Fix:**

1. Choose **Find this name in the metric library**, or **Find archived metrics with this name**, to see the existing metric.
2. If it's the same metric, leave the row unselected and edit the existing metric instead. See [Write metrics](/studios/metrics/how-tos/write-metrics).
3. If it's a different metric, choose **Edit row** for that row, change `name` to a distinct identifier, and choose **Apply and recheck row**.

If the message is "This file repeats the same metric name. Choose a distinct name.", two rows in your own file share a name. Rename one of them.

For saved queries, **Existing match** means a query with the same SQL is already saved. Choose **Attach history evidence** to add your history to it, or **Create a separate query with this SQL**. "This name already exists. Choose another name or use the existing query." means the name is taken.

## An import row shows "Outcome unknown"

**Cause:** Studio sent the row but didn't get a confirmation back, so it may have been saved. Studio says "The request may have completed. This row is locked against retry." and stops the batch.

**Fix:** Don't import the row again. Open the catalog or **Saved queries** in the destination workspace and check whether the item exists. If it does, you're done. If not, start a new import with just that row.

## Fields is locked, or the definition says the JSON is not valid

**Cause:** The definition in **JSON** doesn't parse. Studio shows "The JSON is not valid. Check its quotes, commas and brackets." and keeps **Fields** shut until it does. The reverse also applies: if a JSON array field under **Dimensions, filters, joins and parameters** doesn't parse, **JSON** stays shut.

**Fix:** Correct the JSON where the error appears. Look for a missing comma, an unclosed bracket, or straight quotes replaced with curly ones. Each array field needs a JSON array, and `[]` means none: "Use a JSON array. Use \[] for no declarations."

## Save is blocked

**Symptom:** **Save definition** shows a message instead of saving.

| Message | Cause | Fix |
| - | - | - |
| "Complete the required fields." | A required field is blank: **Formula**, **Warehouse**, **Aggregation type**, **Output name**, or **Output data type** for a metric, or **SQL text** for a saved query. | Fill in the field. |
| "Provide a source entity and alias, with exactly one non-empty table or SQL source." | **Source entity** or **Source alias** is blank, or both or neither of **Source table** and **Source SQL** are set. | Fill in the entity and alias, and use one source only. |
| "The definition version must be a positive, safe integer." | **Definition version** is empty, 0, or not a whole number. | Set it to 1 or more. |
| "Use metric format 1.0-draft.4 for new saves. Earlier definitions are upgraded during review." | `spec_version` in **JSON** is an older format. | Set `spec_version` to `1.0-draft.4`. |
| "Provide a name and an identifier. A revision keeps its existing identity." | **Name** or **Identifier** is blank. | Fill in both. |
| "Choose a destination workspace. Existing items cannot move between workspaces." | No workspace is chosen. | Choose a **Destination workspace**. |
| "This item has changed. Copy your edits, then reopen the current revision." | Someone saved a newer revision while you edited. | Copy your changes, reopen the metric, and apply them to the current revision. |
| "Restore this archived item before revising it." | The metric is archived. | Choose **Restore as a new revision** first. |

If the save reaches Atlan and is refused, the error names a field, such as `definition.version`. A metric whose calculation changed must have a higher **Definition version**. See [Errors](/studios/metrics/references/definition-fields#errors) for every field.

## You can't create or edit anything

**Cause:** Your role or your organization's settings don't allow authoring in this workspace. Studio says why:

| Message | Fix |
| - | - |
| "You can read existing content. Creating and editing require workspace Builder or Admin access." | Ask a workspace admin for the **Builder** or **Admin** role. |
| "Your organization has restricted authoring in this workspace." | Ask your Atlan administrator to allow it, or use another workspace. |
| "Choose a workspace to create or edit." | You're viewing all workspaces. Choose one. |
| "Authoring permissions could not be read. Existing content remains available." | Choose **Retry permissions**. |

## Release is blocked

| What you see | Cause | Fix |
| - | - | - |
| **Release revision N** is unavailable, with "Release history could not be loaded. Retry before an action that can change distribution." | Studio couldn't read the metric's releases. | Choose **Retry**, or reload the page. |
| "This revision has already been released on this channel. Choose another revision or channel." | A revision can ship on a channel only once, even after it's withdrawn. | Edit the metric to save a new revision, then release that. |
| "No active revision is available to release on this channel." | Every active revision has already shipped on this channel. | Save a new revision, or choose another **Release channel**. |
| The catalog shows **Pending review** or **Blocked** | Atlan is holding the newest revision. | An authorized user chooses **Clear the Registry hold** in **More actions**, then releases. |
| The dialog shows **Release requested** | The release is pending checks. "Pending releases wait for the Registry's checks; agents do not get them yet." | Wait, then reload the metric to see it go **Live**. |
| "You do not have permission for this action." | Your role can't release here. | Ask a workspace admin. |

## "The server has not confirmed the result"

**Cause:** Studio sent a save or a release and lost the response, so it can't tell whether it worked. The form or dialog locks so you don't repeat it.

**Fix:**

1. Don't save or release again.
2. Close the dialog and reload the metric.
3. Open **History**. If the new revision or release is there, it went through. If not, try again.

A similar message, "The save could not be confirmed. Do not repeat it: reload, and check History to see whether it went through.", appears when naming a replacement. Follow the same steps.

## An agent reads an old version

**Cause:** One of these:

* **The newest revision isn't released.** Saving never changes what agents get. The catalog's **Release** column shows **Unreleased changes**, and the metric's page says "You are reading revision {n}, which is not released. Agents get {label}."
* **The agent is pinned to a release.** A `registry__get_artifact` call with `release_id` always returns that release.
* **The agent reads another channel.** A release on one channel doesn't change what another channel serves.

**Fix:**

1. In Studio, choose **See what agents get** to open the live version and compare.
2. If the change you want isn't live, release it. See [Release metrics](/studios/metrics/how-tos/release-metrics).
3. Check the agent's `registry__get_artifact` call. Use `channel: "latest"` (or the channel you released on) to always get the live version, or update the pinned `release_id`.

The opposite can happen too. A `registry__get_artifact` call with neither `channel` nor `release_id` reads the newest revision, released or not. Have agents pass `channel` to read only released versions.

## An agent can't find a metric

Work through these in order:

1. **The metric tools are missing.** If `tools/list` has no `extension__metric__search_metrics`, the Metrics app isn't installed. An administrator installs it; see [Install and manage apps](/registry/apps/how-tos/install-apps).
2. **Wrong workspace.** The search tools look in one workspace only. Check the agent passes the `workspace_id` the metric is in. In Studio, the release receipt's **Technical details** shows the **Workspace ID**.
3. **No access.** Every call runs as the agent's signed-in identity. That identity needs at least read access to the workspace.
4. **The metric is archived.** Search leaves out archived metrics. Restore it with **Restore as a new revision**, then release it.
5. **The search words don't match.** Search ranks on the name and description. Try the exact identifier with `name`, add `semantic: true`, or improve the metric's description.
6. **The metric isn't released.** Search finds it, but `registry__get_artifact` with `channel: "latest"` is refused with "no such distributable release". Release it.

If the tool itself refuses the call, check the arguments:

| Message | Fix |
| - | - |
| "`workspace_id` is required: these tools search one workspace." | Pass a `workspace_id`. |
| "Give `query` (ranked search) or `name` (exact resolution)." | Pass one of them. |
| "Tool arguments do not match the declared schema." | Remove or correct arguments the tool doesn't declare, such as a misspelled argument name. |

## The catalog says it could not be read

**Symptom:** "The catalog could not be read. Nothing below is a complete list.", or **Unavailable** in the **Release** column.

**Cause:** Studio couldn't read the catalog or the release history. What it shows is incomplete, not empty.

**Fix:** Reload the page before you rely on the list or act on a metric.

## Related

* [How metrics work](/studios/metrics/concepts): Revisions, releases, and channels.
* [Use metrics with agents](/studios/metrics/how-tos/use-with-agents): The calls agents make.
* [MCP Gateway errors](/gateway/mcp/troubleshooting): Connection and sign-in problems.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.