name: glean-common-errors description: 'Diagnose and fix common Glean API errors including indexing failures, search issues, and permission problems.

Trigger: "glean error", "glean not indexing", "glean search empty", "debug glean".

' allowed-tools: Read, Grep, Bash(curl:*) version: 1.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• enterprise-search
• glean compatibility: Designed for Claude Code

Glean Common Errors

Overview

Glean provides enterprise search across connected data sources with AI-powered results. API integrations involve two distinct token types (indexing vs. client) and a custom datasource model for pushing content. Common errors stem from token type mismatches, permission misconfiguration that silently hides documents from search results, and bulk indexing failures caused by duplicate upload IDs or oversized documents. Stale results are a frequent complaint -- Glean indexes asynchronously, so newly pushed documents may take 1-5 minutes to appear in search. This reference covers authentication, indexing pipeline, and search-time issues.

Error Reference

Error Handler

interface GleanError {
  code: number;
  message: string;
  category: "auth" | "rate_limit" | "indexing" | "permission";
}

function classifyGleanError(status: number, body: string): GleanError {
  if (status === 401) {
    return { code: 401, message: body, category: "auth" };
  }
  if (status === 429) {
    return { code: 429, message: "Rate limit exceeded", category: "rate_limit" };
  }
  if (status === 403 && body.includes("permission")) {
    return { code: 403, message: body, category: "permission" };
  }
  if (status === 400) {
    return { code: 400, message: body, category: "indexing" };
  }
  return { code: status, message: body, category: "auth" };
}

Debugging Guide

Authentication Errors

Glean uses two distinct token types. Indexing tokens authenticate bulk document uploads. Client tokens authenticate search queries and require the X-Glean-Auth-Type: BEARER header. Using the wrong token type returns 403, not 401 -- check the token type first.

Rate Limit Errors

Glean enforces per-token rate limits. Indexing operations should batch documents (up to 100 per request). Search queries are rate-limited per client token. Use Retry-After header when present and implement exponential backoff starting at 2 seconds.

Validation Errors

Bulk index uploads require a unique uploadId per run -- reusing an ID silently drops the upload. Documents must include both id and title fields. Content bodies over 100KB are rejected; truncate or split large documents. New datasources must be registered via adddatasource before any documents can be indexed against them. The datasource field in each document must exactly match the registered datasource name (case-sensitive).

Error Handling

Quick Diagnostic

# Verify client token connectivity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $GLEAN_API_KEY" \
  -H "X-Glean-Auth-Type: BEARER" \
  https://your-domain.glean.com/api/v1/search

Resources

• Glean Developer Portal
• Indexing API Docs

Next Steps

See glean-debug-bundle.