Skip to content

Context7 Platform -- Up-to-date docs for AI agents

fix(cli): surface GitHub API error details when skill download fails (#2786)

Enes Gulesacd0d4640e82
diff --git a/.changeset/slow-adults-bet.md b/.changeset/slow-adults-bet.md
new file mode 100644
index 00000000..4b1089e9
--- /dev/null
+++ b/.changeset/slow-adults-bet.md
@@ -0,0 +1,13 @@
+---
+"ctx7": patch
+---
+
+Surface GitHub API error details when skill download fails (#2363)
+
+Previously, any GitHub API failure during `ctx7 setup` or `ctx7 setup --cli` produced the opaque message "GitHub API error", making it impossible to distinguish a 403 rate-limit from a 401 bad token or a 404 wrong branch.
+
+Changes:
+- `fetchRepoTree` and `fetchDefaultBranch` now extract the HTTP status and GitHub error body, returning descriptive strings like `"HTTP 403: API rate limit exceeded"`
+- `listSkillsFromGitHub` distinguishes a true 404 (repo not found) from other errors (rate-limit, bad credentials) that previously all collapsed into the same silent result
+- When a request fails unauthenticated with a 403/429, a hint is shown: `run \`gh auth login\` or set the GITHUB_TOKEN env var to increase rate limits`
+- Failed skill entries in the setup results table now show a red `✖` with the error detail on its own line instead of embedding it in the status string
diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.ts
index 4039a460..c5b8a3f7 100644
--- a/packages/cli/src/commands/setup.ts
+++ b/packages/cli/src/commands/setup.ts
@@ -384,6 +384,22 @@ async function setupAgent(
};
}
+function logSkillStatus(skillStatus: string, skillPath: string): void {
+ const skillFailed = skillStatus.startsWith("failed:");
+ const skillIcon =
+ skillStatus === "installed" ? pc.green("+") : skillFailed ? pc.red("✖") : pc.dim("~");
+ log.plain(` ${skillIcon} Skill ${skillFailed ? "failed" : skillStatus}`);
+ log.plain(` ${pc.dim(skillPath)}`);
+ if (skillFailed) {
+ log.plain(` ${pc.red(skillStatus.slice("failed: ".length))}`);
+ if (skillStatus.includes("EACCES")) {
+ log.plain(
+ ` ${pc.yellow("tip:")} fix permissions with: ${pc.cyan(`sudo chown -R $(whoami) ${dirname(dirname(skillPath))}`)}`
+ );
+ }
+ }
+}
+
async function setupMcp(agents: SetupAgent[], options: SetupOptions, scope: Scope): Promise<void> {
const transport = resolveTransport(options);
if (transport === "stdio" && options.oauth) {
@@ -420,14 +436,7 @@ async function setupMcp(agents: SetupAgent[], options: SetupOptions, scope: Scop
const ruleIcon = r.ruleStatus === "installed" ? pc.green("+") : pc.dim("~");
log.plain(` ${ruleIcon} Rule ${r.ruleStatus}`);
log.plain(` ${pc.dim(r.rulePath)}`);
- const skillIcon = r.skillStatus === "installed" ? pc.green("+") : pc.dim("~");
- log.plain(` ${skillIcon} Skill ${r.skillStatus}`);
- log.plain(` ${pc.dim(r.skillPath)}`);
- if (r.skillStatus.includes("EACCES")) {
- log.plain(
- ` ${pc.yellow("tip:")} fix permissions with: ${pc.cyan(`sudo chown -R $(whoami) ${dirname(dirname(r.skillPath))}`)}`
- );
- }
+ logSkillStatus(r.skillStatus, r.skillPath);
}
log.blank();
@@ -498,9 +507,10 @@ async function setupCli(options: SetupOptions): Promise<void> {
}> = [];
for (const agentName of agents) {
- installSpinner.text = `Setting up ${getAgent(agentName).displayName}...`;
+ const agentDef = getAgent(agentName);
+ installSpinner.text = `Setting up ${agentDef.displayName}...`;
const r = await setupCliAgent(agentName, scope, downloadData);
- results.push({ agent: getAgent(agentName).displayName, ...r });
+ results.push({ agent: agentDef.displayName, ...r });
}
installSpinner.succeed("Context7 CLI setup complete");
@@ -508,14 +518,7 @@ async function setupCli(options: SetupOptions): Promise<void> {
log.blank();
for (const r of results) {
log.plain(` ${pc.bold(r.agent)}`);
- const skillIcon = r.skillStatus === "installed" ? pc.green("+") : pc.dim("~");
- log.plain(` ${skillIcon} Skill ${r.skillStatus}`);
- log.plain(` ${pc.dim(r.skillPath)}`);
- if (r.skillStatus.includes("EACCES")) {
- log.plain(
- ` ${pc.yellow("tip:")} fix permissions with: ${pc.cyan(`sudo chown -R $(whoami) ${dirname(dirname(r.skillPath))}`)}`
- );
- }
+ logSkillStatus(r.skillStatus, r.skillPath);
const ruleIcon =
r.ruleStatus === "installed" || r.ruleStatus === "updated" ? pc.green("+") : pc.dim("~");
log.plain(` ${ruleIcon} Rule ${r.ruleStatus}`);
diff --git a/packages/cli/src/utils/github.ts b/packages/cli/src/utils/github.ts
index 5ef14d7f..f5518e95 100644
--- a/packages/cli/src/utils/github.ts
+++ b/packages/cli/src/utils/github.ts
@@ -152,15 +152,24 @@ function getGitHubHeaders(): Record<string, string> {
};
}
+async function extractGitHubError(response: Response): Promise<string> {
+ let detail = `HTTP ${response.status}`;
+ try {
+ const body = (await response.json()) as { message?: string };
+ if (body.message) detail += `: ${body.message}`;
+ } catch {}
+ return detail;
+}
+
async function fetchRepoTree(
owner: string,
repo: string,
branch: string,
headers: Record<string, string>
-): Promise<GitHubTreeResponse | null> {
+): Promise<GitHubTreeResponse | { error: string }> {
const treeUrl = `${GITHUB_API}/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`;
const response = await fetch(treeUrl, { headers });
- if (!response.ok) return null;
+ if (!response.ok) return { error: await extractGitHubError(response) };
return (await response.json()) as GitHubTreeResponse;
}
@@ -168,9 +177,9 @@ async function fetchDefaultBranch(
owner: string,
repo: string,
headers: Record<string, string>
-): Promise<{ branch: string } | { status: number }> {
+): Promise<{ branch: string } | { error: string; status: number }> {
const response = await fetch(`${GITHUB_API}/repos/${owner}/${repo}`, { headers });
- if (!response.ok) return { status: response.status };
+ if (!response.ok) return { error: await extractGitHubError(response), status: response.status };
const data = (await response.json()) as { default_branch: string };
return { branch: data.default_branch };
}
@@ -190,10 +199,13 @@ export async function listSkillsFromGitHub(project: string): Promise<GitHubSkill
const headers = getGitHubHeaders();
const branchResult = await fetchDefaultBranch(owner, repo, headers);
- if ("status" in branchResult) return { status: "repo_not_found" };
+ if ("error" in branchResult) {
+ if (branchResult.status === 404) return { status: "repo_not_found" };
+ return { status: "error", error: branchResult.error };
+ }
const treeData = await fetchRepoTree(owner, repo, branchResult.branch, headers);
- if (!treeData) return { status: "error", error: "Could not fetch repository tree" };
+ if ("error" in treeData) return { status: "error", error: treeData.error };
const skillMdFiles = treeData.tree.filter(
(item) => item.type === "blob" && item.path.toLowerCase().endsWith("skill.md")
@@ -250,8 +262,12 @@ export async function downloadSkillFromGitHub(
const ghHeaders = getGitHubHeaders();
const treeData = await fetchRepoTree(owner, repo, branch, ghHeaders);
- if (!treeData) {
- return { files: [], error: `GitHub API error` };
+ if ("error" in treeData) {
+ const hint =
+ !ghHeaders["Authorization"] && /403|429|rate/.test(treeData.error)
+ ? " — run `gh auth login` or set the GITHUB_TOKEN env var to increase rate limits"
+ : "";
+ return { files: [], error: `GitHub API error: ${treeData.error}${hint}` };
}
const skillFiles = treeData.tree.filter(