crewAIInc/crewAI · error · SystemExit

Skill {ref} not found. Ensure it has been published and you

Error message

Skill {ref} not found. Ensure it has been published and you have access.

What it means

The registry API returned HTTP 404 for `GET skill org/name`. This means either no skill with that org/name pair has been published, or it exists but the authenticated organization does not have access to it (skills are org-scoped, with no public visibility).

Source

Thrown at lib/cli/src/crewai_cli/skills/main.py:119

            or len(Path(org).parts) != 1
            or len(Path(name).parts) != 1
        ):
            console.print(
                "[red]Invalid skill reference: org and name must be single, "
                "non-empty path segments (no slashes, no '..').[/red]"
            )
            raise SystemExit(1)

        self._print_current_organization()
        console.print(f"[bold blue]Downloading skill {ref}...[/bold blue]")

        get_response = self.plus_api_client.get_skill(org, name)

        if get_response.status_code == 404:
            console.print(
                f"[red]Skill {ref} not found. Ensure it has been published and you have access.[/red]"
            )
            raise SystemExit(1)
        if get_response.status_code != 200:
            console.print(
                f"[red]Failed to download skill {ref}: {get_response.status_code}[/red]"
            )
            raise SystemExit(1)

        data = get_response.json()
        version = data.get("latest_version") or data.get("version")

        download_url = data.get("download_url")
        if download_url:
            import httpx

            dl_response = httpx.get(download_url, follow_redirects=True)
            dl_response.raise_for_status()
            archive_bytes = dl_response.content
        else:
            encoded = data.get("file", "")

View on GitHub (pinned to 754d7323be)

Solutions

Verify org and name exactly as published (check with the author or the registry UI), and re-run `crewai skill install @correct-org/correct-name`.
Run `crewai org switch <org_id>` to switch to the org that owns the skill, then retry (404 is also returned when access is denied).
If you authored the skill, publish it first with `crewai skill publish` from its directory.

Example fix

# before
crewai skill install @myteam/writing-tools   # 404: never published under this org
# after
crewai org switch acme-prod
crewai skill install @acme-prod/writing-tools

Defensive patterns

Strategy: try-catch

Validate before calling

import httpx

def skill_exists(client, org: str, name: str, token: str) -> bool | None:
    """True/False if registry answers definitively; None on transient failure."""
    r = client.get_skill(org, name)
    if r.status_code == 200:
        return True
    if r.status_code == 404:
        return False
    return None

Try / catch

import subprocess, sys

try:
    subprocess.run(["crewai", "skill", "install", ref], check=True)
except subprocess.CalledProcessError as e:
    if "not found" in (e.stderr or ""):  # 404 branch message
        print(f"{ref} is unpublished or not shared with your org")
        sys.exit(2)
    raise

Prevention

Confirm org and name from the registry UI or the publisher before scripting installs.
Make sure you are switched to the org the skill was published to (`crewai org switch`).
In automation, treat a 404 message as a distinct case from other download failures.

When it happens

Trigger: Calling `crewai skill install @org/name` where the skill was never published, was published under a different org, or the currently authenticated token belongs to an org without access. The 404 branch fires on `self.plus_api_client.get_skill(org, name).status_code == 404`.

Common situations: Typos in org or name; trying to install a skill a teammate published to their personal org while you are switched to a different org; not logged in / expired token being treated as a different org; skill still in draft and never published.

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/97078fcd8acd9a9e. Report an issue: GitHub.