upstash/context7 · warning

Failed to download ${skill.name}: ${downloadData.error}

Error message

Failed to download ${skill.name}: ${downloadData.error}

What it means

Emitted in the install loop of `context7 skill add` (interactive flow). Each selected skill is fetched via downloadSkill(project, name), which first calls the Context7 registry (getSkill) and, on failure, falls back to GitHub. If both paths return an error, downloadData.error is printed with log.warn and the loop continues to the next skill — one failed download does not abort the batch.

Source

Thrown at packages/cli/src/commands/skill.ts:417

    log.warn("Installation cancelled");
    return;
  }

  const targetDirs = getTargetDirs(targets);

  const installSpinner = ora("Installing skills...").start();

  let permissionError = false;
  const failedDirs: Set<string> = new Set();
  const installedSkills: string[] = [];

  for (const skill of selectedSkills) {
    try {
      installSpinner.text = `Downloading ${skill.name}...`;
      const downloadData = await downloadSkill(skill.project, skill.name);

      if (downloadData.error) {
        log.warn(`Failed to download ${skill.name}: ${downloadData.error}`);
        continue;
      }

      installSpinner.text = `Installing ${skill.name}...`;

      const [primaryDir, ...symlinkDirs] = targetDirs;

      try {
        await installSkillFiles(skill.name, downloadData.files, primaryDir);
      } catch (dirErr) {
        const error = dirErr as NodeJS.ErrnoException;
        if (error.code === "EACCES" || error.code === "EPERM") {
          permissionError = true;
          failedDirs.add(primaryDir);
        }
        throw dirErr;
      }

View on GitHub (pinned to 5284672feb)

Solutions

1. Re-run using the exact project/skill ID shown by `context7 skill search <query>`
2. If the error mentions 403/429 or rate: run `gh auth login` or export GITHUB_TOKEN before retrying
3. Check connectivity: curl -I https://context7.com and curl -I https://api.github.com
4. For private skills, ensure the GitHub account/token has access to the source repository

Example fix

# before — anonymous, fallback hits GitHub rate limit
context7 skill add

# after — authenticated, higher rate limit
gh auth login
# or: export GITHUB_TOKEN=ghp_xxx
context7 skill add

// pre-flight: confirm the skill resolves before batch install
// CLI: context7 skill info <project>/<name>  (exits non-zero if missing)
// API-equivalent in code:
const res = await fetch(`https://context7.com/api/v1/skills/${project}/${name}`);
if (!res.ok) skip(name, `registry ${res.status}`);

function isDownloadOk(r: { files?: unknown[]; error?: string }): r is { files: NonNullable<typeof r.files> } {
  return !r.error && Array.isArray(r.files) && r.files.length > 0;
}

When it happens

Trigger: Skill or project name that does not exist in the registry (404 from getSkill) AND has no reachable GitHub fallback; GitHub fallback failing with 403/429 rate limit when unauthenticated; invalid skill GitHub URL; skill path containing zero files; network/DNS failure reaching context7.com or api.github.com.

Common situations: Anonymous GitHub API rate limits (60 req/hr) on CI or shared IPs breaking the fallback; skill removed/renamed in the registry since the picker cached it; private-repo skills fetched without authorization; corporate proxies blocking api.github.com.

Related errors

• Failed to fetch ${item.path}: ${fileResponse.status}
• downloadData.error || "no files"
• errorBody.error || errorBody.message || res.statusText
• Please try again
• Skipping file with unsafe path: ${item.path}

AI-assisted analysis of upstash/context7@5284672feb (2026-08-18). Data as JSON: /api/errors/397b317f6b00b888. Report an issue: GitHub.