Help & Reference

How to use the Known Error Database, taxonomy reference, and tips for searching.

What is a Known Error?

A Known Error (KE) is a documented platform issue with a confirmed root cause and at least one known workaround. Use KEDB to look up issues before paging engineering, to drop the right workaround into a ticket fast, and to feed pattern detection back into product fixes.

Quick navigation

Known Errors
Browse all KE entries with filters.
Hybrid search
Semantic + full-text. Best entry point.
Dashboard
Counts by status, severity, and domain.
+ New entry
Document a new known error.

KE ID format

Every entry has an immutable id: KE-YYYY-NNNN

  • YYYY — 4-digit year of creation
  • NNNN — zero-padded sequence within that year (resets each January)
  • Generated server-side under a Postgres advisory lock — no collisions on concurrent creates

Search tips

The search page runs a hybrid query against PGVector embeddings and Postgres tsvector, combined via Reciprocal Rank Fusion (k=60).

  • Symptom phrasing wins for semantic. e.g. "redis cache misses after deploy"
  • Exact tokens win for full-text. e.g. "502 origin shield", "OPcache reset"
  • Result badge tells you which path matched: semantic, fulltext, or hybrid
  • Score is the RRF-fused rank, not a similarity percentage

Dual taxonomy

Each KE carries two parallel taxonomies. Both are optional but encouraged.

Simplified Taxonomy (reporting)

For exec dashboards and squad ownership. Aligns with Pantheon's L1/L2/L3.

  • st_l1 — top-level area (e.g. Platform, CMS)
  • st_l2 — sub-area
  • st_squad_owner — owning squad

KEDB Error Taxonomy (diagnosis)

For triage and pattern matching.

  • error_domain — PLATFORM, CMS, INTEGRATION, CONFIGURATION
  • error_category — fine-grained (e.g. PLAT-CACHE, CMS-MODULE)
  • root_cause_type — bug, limitation, misconfiguration, incompatibility, resource_exhaustion, external_dependency
  • platform_constraint — true if Pantheon-specific

Status lifecycle

  • open — confirmed, no workaround yet
  • workaround — workaround documented, no permanent fix
  • fix_in_progress — engineering ticket open
  • resolved — permanent fix shipped, sets resolved_at
  • wont_fix — by design / accepted limitation. Soft-delete via DELETE also lands here

Severity

  • critical — outage / data loss potential
  • high — feature broken for many sites
  • medium — degraded experience or single-site impact
  • low — cosmetic / edge case

API & integrations

  • Backend: https://ai-context-api (Cloud Run) — REST under /kedb
  • MCP tools (Claude Code): search_kedb, get_kedb_entry
  • Auth: Cloud Run IAM (ID token) for backend; Auth0 SSO for this UI

Need to add a category or taxonomy value?

The error_category field is currently free-text. A controlled vocabulary (PLAT-CACHE, CMS-MODULE, INT-EMAIL, …) is on the roadmap. Until then: pick a value that matches existing entries — the search page is your friend for finding the prevailing convention.