chakra-ui/chakra-ui · error · Error

Failed to search docs: ${res.status} ${res.statusText}

Error message

Failed to search docs: ${res.status} ${res.statusText}

What it means

Thrown by searchDocs when GET {CHAKRA_DOCS_URL}/api/search?query={query} returns non-2xx. The query is URL-encoded before sending. The message reports status and statusText; a 400/422 can indicate an empty or malformed query, while 5xx indicates the docs origin is down.

Source

Thrown at packages/cli/src/utils/fetch.ts:150

  const json: unknown = await res.json()
  return parseWithSchema(json, z.unknown(), `example for "${component}"`)
}

export async function fetchTheme() {
  const res = await request(`${docsUrl("/api/theme")}`)
  if (!res.ok) {
    throw new Error(`Failed to fetch theme: ${res.status} ${res.statusText}`)
  }
  const json: unknown = await res.json()
  return parseWithSchema(json, themeIndexSchema, "theme")
}

export async function searchDocs(query: string): Promise<SearchItem[]> {
  const res = await request(
    `${docsUrl("/api/search")}?query=${encodeURIComponent(query)}`,
  )
  if (!res.ok) {
    throw new Error(`Failed to search docs: ${res.status} ${res.statusText}`)
  }
  const json: unknown = await res.json()
  return parseWithSchema(json, searchResultsSchema, "search")
}

export async function fetchProBlock(
  category: string,
  id: string,
  apiKey: string,
) {
  const res = await request(
    `https://pro.chakra-ui.com/api/blocks/${category}/${id}`,
    {
      headers: {
        "x-api-key": apiKey,
      },
    },
  )

View on GitHub (pinned to 13692aee26)

Solutions

1. Ensure the query is a non-empty string before calling searchDocs.
2. Open {CHAKRA_DOCS_URL}/api/search?query=button in a browser to confirm the endpoint.
3. Retry on 5xx; verify CHAKRA_DOCS_URL is the bare origin.
4. Upgrade @chakra-ui/cli to align with the current docs search API.

Example fix

// before: empty query can produce a 400
const results = await searchDocs(query);

// after: guard the input
if (!query || !query.trim()) {
  throw new Error('searchDocs requires a non-empty query');
}
const results = await searchDocs(query.trim());

// Guard the query before calling searchDocs
function isValidQuery(q: unknown): q is string {
  return typeof q === 'string' && q.trim().length > 0;
}
if (!isValidQuery(query)) {
  throw new Error('searchDocs requires a non-empty query string');
}

function isNonEmptyQuery(value: unknown): value is string {
  return typeof value === 'string' && value.trim().length > 0;
}

// Retry transient search failures; surface 4xx as bad-query
try {
  return await searchDocs(query);
} catch (err) {
  const msg = (err as Error).message;
  if (/\b4\d\d\b/.test(msg) && !/429/.test(msg)) throw new Error('Bad search query');
  throw err;
}

When it happens

Trigger: GET /api/search?query=... returns non-2xx — most often a 400 for an unsupported/empty query, a 404 if the search path moved, or 5xx during a docs deploy.

Common situations: Empty query string passed (encodeURIComponent still yields empty); docs search index rebuilding (5xx); CHAKRA_DOCS_URL misconfigured; search endpoint renamed in a newer docs version; proxy returns an error page.

Related errors

• Failed to fetch component list: ${res.status} ${res.statusTe
• Failed to fetch props for "${component}": ${res.status} ${re
• Failed to fetch example for "${component}": ${res.status} ${
• Failed to fetch theme: ${res.status} ${res.statusText}
• Failed to fetch pro blocks: ${res.status} ${res.statusText}

AI-assisted analysis of chakra-ui/chakra-ui@13692aee26 (2026-08-12). Data as JSON: /api/errors/fd05d4155e20066a. Report an issue: GitHub.