技能 编程开发 Glean常见错误诊断与修复指南

Glean常见错误诊断与修复指南

v20260423
glean-common-errors
本指南旨在帮助用户排查和解决在使用Glean企业搜索API时遇到的常见技术错误。内容涵盖认证失败、索引流程故障、权限限制和API限速等关键问题,提供了详细的错误码、根本原因和实用的修复步骤。
获取技能
401 次下载
概览

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

CodeMessageCauseFix
401UnauthorizedInvalid or expired API tokenRegenerate at Admin > Settings > API Tokens
403Wrong token typeUsing indexing token for search APIIndexing API needs indexing token; Client API needs client token with X-Glean-Auth-Type: BEARER
400uploadId already usedDuplicate bulk upload identifierGenerate a unique UUID per upload run
400document too largeDocument body exceeds 100KB limitTruncate or split content before indexing
400invalid datasourceDatasource not registeredCreate datasource first via adddatasource endpoint
400missing required fieldDocument lacks id or titleEnsure every document has both id and title fields
403Permission deniedDocument visibility restrictedSet allowAnonymousAccess: true or add user/group to permissions
429Rate limit exceededToo many API requestsImplement exponential backoff; batch indexing calls

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

ScenarioPatternRecovery
No search results after indexingProcessing delay (1-5 min)Wait 5 minutes, then verify with direct document lookup
Stale results returnedIndex not refreshedTrigger re-index; check datasource sync schedule
Permission mismatchUser lacks document accessAdd user/group to document permissions or enable anonymous access
Bulk upload silently droppedDuplicate uploadIdAlways generate fresh UUID per upload run
Token type confusion403 on search or indexVerify correct token type for the API being called

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

Next Steps

See glean-debug-bundle.

信息
分类 编程开发
名称 glean-common-errors
版本 v20260423
大小 4.9KB
更新时间 2026-04-28
语言