File operation errors

Errors from file list, file get, file upload, file download, and file delete. Run atlanai doctor and atlanai auth status first. Authentication failures and workspace context issues are the most common causes.

​

file list returns an empty result

The active workspace has no file artifacts, or the workspace context points to the wrong workspace.

​

Cause

The CLI resolves file listing against the active workspace context. If the context points to a workspace with no files, or to the wrong workspace, the result is empty.

​

Solution

Confirm the active workspace before investigating further.

1. Run atlanai context show to confirm the active workspace.
2. Switch with atlanai context use if the context points to the wrong workspace, or pass --workspace <id> explicitly.
3. Rerun file list.

---

​

file get returns “not found”

The file ID does not exist in the active workspace, or the file has been archived.

​

Cause

The ID was entered incorrectly, belongs to a different workspace, or the file has been archived. Archived files do not appear in the default listing.

​

Solution

Verify the file ID before retrying.

1. Run atlanai file list to find the correct file ID.
2. If the file was archived, contact your workspace administrator to restore it.

---

​

Upload rejected with “duplicate path”

A file with the same published path already exists in the workspace.

​

Cause

The --as value resolves to a path that is already occupied. The CLI does not overwrite existing files silently.

​

Solution

Resolve the path conflict before uploading.

1. Choose a different --as value, or archive the existing file with atlanai file delete file_123.
2. Rerun the upload.

---

​

Permission denied on upload

The authenticated account does not have write access to the target workspace.

​

Cause

Upload requires write permission on the workspace. Read-only accounts and viewers receive a permission error.

​

Solution

Confirm your access level before retrying.

1. Run atlanai workspace list to confirm the workspace and your access level.
2. Ask your workspace administrator to grant upload permission.
3. Retry the upload after the permission is updated.

---

​

Binary download fails without --output

The CLI declines to write binary content to the terminal.

​

Cause

Binary file types cannot be safely written to stdout. The CLI requires an explicit output path for binary downloads and exits without writing content.

​

Solution

Rerun the command with the output flag set.

1. Rerun file download with --output ./filename.ext to write the file locally.

---

​

Download stops before completion

The file is larger than the 64 MiB download limit.

​

Cause

file download enforces a 64 MiB cap. Files above this limit cannot be fully downloaded through the CLI.

​

Solution

Contact Atlan support to retrieve files above the size limit.

---

​

Version not found

The version number does not exist for this file.

​

Cause

The version ordinal passed to --version is out of range for the file’s published history.

​

Solution

List available versions before retrying the download.

1. Run atlanai file versions file_123 to list all available versions.
2. Confirm the correct ordinal for the intended snapshot.
3. Rerun the download with the correct --version value.

---

​

Archive targets the wrong file

The wrong file ID was passed to atlanai file delete.

​

Cause

File IDs can look similar. Passing the wrong ID archives a file that was not intended to be removed.

​

Solution

Confirm the file before archiving.

1. Run atlanai file get file_123 to confirm the published path and workspace.
2. Verify this is the intended file before proceeding.
3. Run atlanai file delete file_123 only after confirming the correct ID. Archiving cannot be reversed through the CLI. Contact your workspace administrator to restore an archived file.

---

​

Command fails with an authentication error

The stored credential has expired.

​

Cause

CLI credentials have a time-to-live. An expired token causes authentication errors on any command that contacts the Registry.

​

Solution

Re-authenticate and confirm the session is valid.

1. Run atlanai auth login to re-authenticate.
2. Confirm the session is active with atlanai auth status.
3. Retry the command.

​

See also

• Find and inspect files: List file artifacts and inspect records.
• Upload files: Upload a new file or replace an existing one.
• Download files: Download the current or a specific version.
• Archive files: Remove a file from default discovery.
• Run diagnostics: Inspect installation, daemon logs, and authentication state.

​

Need help

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