Skip to main content
Preview 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.
  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. 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 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:

​
Release is blocked

​
”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 , which is not released. Agents get .”
  • 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.
  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.
  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:

​
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.