Skill operation errors

Errors from skill validate, skill push, skill list, skill rollback, skill install, skill publish, and skill hooks install. Run atlanai doctor and atlanai auth status before investigating. Most failures trace back to a failed health check or an expired credential.

​

skill validate reports schema errors

The skill configuration does not meet the required format.

​

Cause

One or more fields in SKILL.md or the skill configuration violate the schema. The CLI validates the full document and reports every failure in a single run.

​

Solution

The error output lists each failing field and the constraint it violates.

1. Read the error output to identify each failing field and constraint.
2. Fix the reported fields in SKILL.md or the skill configuration.
3. Rerun skill validate before pushing.

---

​

skill push reports a workspace mismatch

The active workspace context does not match the workspace the skill was previously published to.

​

Cause

The CLI compares the active workspace context against the skill’s registered workspace. A mismatch causes the push to stop before writing anything.

​

Solution

Confirm the active workspace before retargeting the push.

1. Run atlanai context show to confirm the active workspace.
2. Switch context with atlanai context use, or pass --workspace <id> explicitly to target the correct workspace.
3. Retry skill push.

---

​

Push rejected with an authentication error

The stored credential has expired or lacks publish permission.

​

Cause

Publishing requires write permission on the target workspace. An expired token or an account without publish access causes the push to be rejected.

​

Solution

Re-authenticate and confirm the account has the required permission.

1. Run atlanai auth login to re-authenticate.
2. Confirm the session is valid with atlanai auth status.
3. Verify the account has publish permission on the target workspace.
4. Retry skill push.

---

​

skill list returns no results

The active workspace has no published skills, or the workspace context points to the wrong workspace.

​

Cause

The CLI lists skills in the active workspace only. A wrong context or a workspace with no published skills returns an empty result.

​

Solution

Confirm the workspace context 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.
3. Rerun skill list.

---

​

skill rollback dry-run shows the wrong version

The version ordinal passed to --to does not match the intended version.

​

Cause

Version ordinals are assigned in publishing order and may not match semantic version numbers. Passing the wrong ordinal targets the wrong snapshot.

​

Solution

List all published versions before running the rollback.

1. Run atlanai skill versions skill_123 to list all published versions.
2. Confirm the correct ordinal for the intended snapshot.
3. Rerun the rollback with the correct --to value.

---

​

Approve or archive action fails

The authenticated account does not have the required permission for this workspace.

​

Cause

Approve and archive operations require elevated permissions. Regular contributors do not have these permissions by default.

​

Solution

Confirm the required permission with your workspace administrator.

1. Confirm your current role with the workspace administrator.
2. Ask the administrator to grant the required permission.
3. Retry the operation after the permission is updated.

---

​

skill install stops with a lockfile conflict

The lockfile is missing or its digests do not match the current .atlan/package.json.

​

Cause

skill install verifies every skill against the lockfile before copying it. A missing or mismatched lockfile causes the command to stop.

​

Solution

Resolve the lockfile before retrying the install.

1. Run the lockfile update command described in Sync skills from GitHub.
2. Retry skill install.

---

​

skill publish --changed-since publishes unexpected skills

The base commit reference resolves to a broader diff than expected.

​

Cause

The commit reference includes more changed files than intended. This can happen when a stale or ambiguous reference is used.

​

Solution

Preview the diff before running publish.

1. Run git diff <commit> --name-only to preview the files included in the reference.
2. Use the merge base commit for pull request jobs, or HEAD~1 for post-merge jobs.
3. Confirm the diff contains only the expected changes.
4. Run skill publish --changed-since with the confirmed reference.

---

​

See also

• Validate and publish skill: Validate and push skills to the Registry.
• Inspect and restore skills: List, inspect, roll back, and archive published skills.
• Manage packages: Install and wire skill dependencies for a repository-managed coding agent.
• Run diagnostics: Inspect installation, daemon logs, and authentication state.

​

Need help

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