shadcn-ui/ui · error · RegistrySourceFileError

Failed to read GitHub source file "${filePath}" from ${forma

Error message

Failed to read GitHub source file "${filePath}" from ${formatGitHubSource(address)}. ${guidance.detail}

What it means

This error is thrown after a successful raw.githubusercontent.com fetch when reading the response body exceeds the library's size limit — readGitHubResponseTextWithLimit raises a GitHubTransportError with kind 'oversize'. The file path, source repo, and size-limit guidance (getGitHubTransportFailureGuidance) are attached to a RegistrySourceFileError with reason 'github-source-file'. It protects the CLI from buffering arbitrarily large files fetched from GitHub raw.

Source

Thrown at packages/shadcn/src/registry/github.ts:408

        reason: "github-source-file",
        url,
        statusCode: response.status,
        source: formatGitHubSource(address),
        filePath,
      },
      suggestion:
        filePath === "registry.json"
          ? 'The GitHub repository and ref were resolved, but raw.githubusercontent.com did not return a root registry.json file. Check that the public repository has registry.json at its root and that raw.githubusercontent.com is accessible from this network. If this is a private repository, run "gh auth login" or set GH_TOKEN to a token with read access.'
          : "Check that the file path exists in the public GitHub repository.",
    })
  }

  try {
    return await readGitHubResponseTextWithLimit(response)
  } catch (error) {
    if (error instanceof GitHubTransportError && error.kind === "oversize") {
      const guidance = getGitHubTransportFailureGuidance(error, "token")
      throw new RegistrySourceFileError(filePath, undefined, {
        message: `Failed to read GitHub source file "${filePath}" from ${formatGitHubSource(
          address
        )}. ${guidance.detail}`,
        context: {
          reason: "github-source-file",
          source: formatGitHubSource(address),
          filePath,
        },
        suggestion: guidance.suggestion,
      })
    }
    throw error
  }
}

function buildGitHubRawUrl(
  address: GitHubSource,
  resolvedSha: string,

View on GitHub (pinned to 683a5a9b37)

Solutions

1. Reduce the size of the offending file — split a large registry.json into multiple smaller registry files and reference items across them
2. Check you resolved the right repo/ref: an oversized file often means you pointed at the wrong repository or a branch containing a generated/bundled registry.json
3. Remove inlined content (base64 assets, bundled code) from the registry file and reference files by path instead
4. If you control the consumer, fetch the file yourself with a higher/no limit and pass the parsed content instead of the remote URL
5. Report/upgrade the library in case a newer version raises the size limit for legitimate large registries

Example fix

// before: one giant registry.json (multi-MB) -> oversize error
{ "items": [ /* 5,000 components with inlined content */ ] }

// after: split into smaller registries
// registry.json
{ "items": [{ "name": "ui", "registry": "./ui-registry.json" }] }
// ui-registry.json
{ "items": [ /* smaller subset */ ] }

// Before pointing the registry at a GitHub raw file, check its size via the GitHub API
async function assertRegistryFileSize(owner: string, repo: string, ref: string, path: string, maxBytes: number) {
  const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${ref}`, {
    headers: process.env.GH_TOKEN ? { Authorization: `Bearer ${process.env.GH_TOKEN}` } : {},
  })
  if (!res.ok) throw new Error(`Cannot stat ${path}: HTTP ${res.status}`)
  const { size } = await res.json()
  if (size > maxBytes) {
    throw new Error(`${path} is ${size} bytes, exceeding the ${maxBytes}-byte fetch limit`)
  }
}

function isRegistrySourceFileError(e: unknown): e is RegistrySourceFileError {
  return e instanceof RegistrySourceFileError
}
function isGitHubSourceFileOversize(e: unknown): boolean {
  return (
    isRegistrySourceFileError(e) &&
    (e.context as any)?.reason === "github-source-file" &&
    /size|large|limit/i.test(e.message)
  )
}

try {
  const content = await fetchGitHubSourceFile(address, resolvedSha, filePath)
} catch (error) {
  if (isRegistrySourceFileError(error) && (error.context as any)?.reason === "github-source-file" && /size|large|limit/i.test(error.message)) {
    // split or trim the registry file, or fetch it out-of-band with a higher limit
    throw new Error(`Registry file too large: ${filePath}. Split the registry or reduce its size.`)
  }
  throw error
}

When it happens

Trigger: Calling a registry content fetch where ref resolution and the HTTP fetch both succeed, but the registry file (e.g. registry.json or a referenced file) returned by raw.githubusercontent.com is larger than the built-in response size limit, so readGitHubResponseTextWithLimit rejects with an 'oversize' GitHubTransportError.

Common situations: A registry.json that grew very large (thousands of components, inlined content, or generated blobs); accidentally pointing the registry at a repo whose registry.json is a build artifact/minified bundle; generated registries that inline base64 or full file contents; hitting the limit right after adding many items to a monorepo registry.

Related errors

• Something went wrong fetching the registry icons.
• Failed to fetch components from registry.
• VALIDATION_ERROR
• FETCH_ERROR
• Failed to fetch components from registry.

AI-assisted analysis of shadcn-ui/ui@683a5a9b37 (2026-08-27). Data as JSON: /api/errors/063358b5d64e51e2. Report an issue: GitHub.