Execute Algolia incident response: triage search failures, distinguish
Algolia-side vs your-side issues, apply fallbacks, and run postmortems.
Trigger: "algolia incident", "algolia outage", "algolia down",
"algolia on-call", "algolia emergency", "algolia broken", "search is down".
allowed-tools
Read, Grep, Bash(curl:*), Bash(npm:*)
version
1.7.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","search","algolia"]
compatibility
Designed for Claude Code
Algolia Incident Runbook
Overview
Rapid incident response procedures for Algolia search failures. Algolia's infrastructure is distributed across multiple data centers with automatic failover, so true Algolia outages are rare. Most incidents are caused by API key issues, settings drift, or indexing pipeline failures on your side.
Prerequisites
Current incident owner, communications channel, and an approved escalation path.
Read-only access to Algolia status, application metrics, and a representative search request.
A defined production index and a safe way to distinguish it from staging before taking remediation action.
Instructions
Use the severity classification and triage sequence below to establish impact before changing settings or reindexing. Record timestamps, request IDs, and the decision owner as the incident progresses.
Examples
The decision tree, remediation table, and communication templates are executable incident examples: choose the branch matching observed impact and send only the update appropriate to the confirmed severity.
// Check if index is emptyconst { items } = await client.listIndices();
const target = items.find(i => i.name === 'products');
console.log(`products: ${target?.entries ?? 'NOT FOUND'} records`);
// If empty, trigger emergency reindexif (!target || target.entries === 0) {
console.log('Index is empty — triggering emergency reindex');
// Import your reindex functionawaitfullReindex();
}
High Latency — Enable Fallback
// Circuit breaker: switch to DB search if Algolia is slowconstTIMEOUT_MS = 2000;
constFAILURE_THRESHOLD = 5;
let failures = 0;
asyncfunctionsearchWithCircuitBreaker(query: string) {
if (failures >= FAILURE_THRESHOLD) {
console.warn('Circuit open: using database fallback');
returndatabaseSearch(query);
}
try {
const controller = newAbortController();
const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
const result = await client.searchSingleIndex({
indexName: 'products',
searchParams: { query, hitsPerPage: 20 },
});
clearTimeout(timeout);
failures = 0; // Reset on successreturn result;
} catch (error) {
failures++;
console.error(`Algolia failure ${failures}/${FAILURE_THRESHOLD}:`, error);
returndatabaseSearch(query);
}
}
Communication Templates
Internal (Slack/PagerDuty)
P[1-4] INCIDENT: Algolia Search
Status: INVESTIGATING | IDENTIFIED | MONITORING | RESOLVED
Impact: [Users cannot search / Search is slow / Results are stale]
Root cause: [API key expired / Index empty / Algolia incident]
Mitigation: [Fallback enabled / Key rotated / Waiting for Algolia]
Next update: [Time]
Owner: @[name]
Postmortem Template
## Incident: Search [Outage/Degradation]**Date:** YYYY-MM-DD HH:MM–HH:MM UTC
**Duration:** X hours Y minutes
**Severity:** P[1-4]
**Detection:** [Alert name / User report / Status page]
### Timeline- HH:MM — First alert fired
- HH:MM — Triage started, identified [root cause]
- HH:MM — Mitigation applied: [action]
- HH:MM — Resolved, monitoring
### Root Cause
[Technical explanation: what broke and why]
### Impact- Search availability: X% during incident
- Users affected: ~N
### Action Items- [ ] [Fix] — Owner — Due date
- [ ] [Prevent] — Owner — Due date
- [ ] [Detect faster] — Owner — Due date
Output
The runbook produces a severity decision, a recorded mitigation path, and a stakeholder update backed by observed search impact. It also identifies when to escalate to Algolia with the diagnostic evidence they need.
Error Handling
Issue
Cause
Solution
Can't reach status.algolia.com
Your network issue
Use mobile, VPN, or check @algloiastatus on Twitter
Triage script fails
Missing env vars
Set ALGOLIA_APP_ID, ALGOLIA_ADMIN_KEY, ALGOLIA_SEARCH_KEY
