From algolia-pack
Diagnoses and fixes common Algolia API errors: 400, 403, 404, 429, ApiError, RetryError, indexing failures. Includes curl tests, bash checks, and TypeScript examples.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin algolia-packThis skill is limited to using the following tools:
Quick reference for the most common Algolia errors, their root causes, and fixes. All examples use `algoliasearch` v5 client error types.
Triages Algolia search failures: checks status page, API connectivity, query responses, index stats via bash; distinguishes service vs app issues; guides fixes and postmortems.
Provides patterns for Algolia search implementation using React InstantSearch hooks, indexing strategies, relevance tuning, and Next.js SSR integration.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Share bugs, ideas, or general feedback.
Quick reference for the most common Algolia errors, their root causes, and fixes. All examples use algoliasearch v5 client error types.
ApiError: Invalid Application-ID or API key
Cause: App ID or API key is wrong, expired, or deleted.
Fix:
# Verify your env vars are set
echo "APP_ID: $ALGOLIA_APP_ID"
echo "KEY set: ${ALGOLIA_ADMIN_KEY:+yes}"
# Test with curl
curl -s "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" \
-H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
-H "X-Algolia-API-Key: ${ALGOLIA_ADMIN_KEY}" | head -c 200
Get fresh keys: dashboard.algolia.com > Settings > API Keys.
ApiError: Method not allowed with this API key
Cause: Using a Search-Only key for a write operation (saveObjects, setSettings, etc.).
Fix: Use the Admin API key for write operations. Search-Only keys only permit search ACL.
// Wrong: search-only key for indexing
const client = algoliasearch(appId, searchOnlyKey);
await client.saveObjects({ ... }); // 403
// Right: admin key for indexing
const client = algoliasearch(appId, adminKey);
await client.saveObjects({ ... }); // Works
ApiError: Index products_staging does not exist
Cause: Searching an index that hasn't been created yet. Algolia creates indices lazily on first saveObjects.
Fix: Index some data first, or check the index name for typos:
# List all indices in your app
curl -s "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" \
-H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
-H "X-Algolia-API-Key: ${ALGOLIA_ADMIN_KEY}" | jq '.items[].name'
ApiError: Too Many Requests
Cause: API key's maxQueriesPerIPPerHour exceeded, or server-side indexing rate limit hit.
Fix:
// Algolia's built-in retry handles transient 429s.
// For sustained rate limits:
// 1. Reduce batch frequency
const BATCH_SIZE = 500; // Down from 1000
// 2. Add delay between batches
for (const batch of chunks) {
await client.saveObjects({ indexName: 'products', objects: batch });
await new Promise(r => setTimeout(r, 200)); // 200ms pause between batches
}
// 3. Check/increase key rate limit
// Dashboard > Settings > API Keys > Edit key > Rate limit
ApiError: Record at the position 0 is too big size=15234 bytes. Contact us if you need a higher quota.
Cause: Single record exceeds 10KB (free/Build plan) or 100KB (paid plans).
Fix:
// Strip unnecessary fields before indexing
function trimForAlgolia(record: any) {
const { full_html, raw_content, internal_notes, ...searchable } = record;
return searchable;
}
// Or split long text into chunks
function truncateDescription(record: any, maxChars = 5000) {
return {
...record,
description: record.description?.substring(0, maxChars),
};
}
ApiError: Attribute "price" is not in attributesForFaceting
Cause: Using filters or facetFilters on an attribute not configured for faceting.
Fix:
await client.setSettings({
indexName: 'products',
indexSettings: {
attributesForFaceting: ['category', 'brand', 'filterOnly(price)', 'filterOnly(in_stock)'],
},
});
// Wait for settings to propagate
RetryError: Unreachable hosts - yourass might not be connected to the internet
Cause: Network/DNS issue. Can't reach *.algolia.net or *.algolianet.com.
Fix:
# Test DNS resolution
nslookup ${ALGOLIA_APP_ID}-dsn.algolia.net
# Test HTTPS connectivity
curl -v "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" 2>&1 | grep "Connected to"
# Check firewall — Algolia needs outbound HTTPS (443) to:
# ${APP_ID}.algolia.net
# ${APP_ID}-1.algolianet.com
# ${APP_ID}-2.algolianet.com
# ${APP_ID}-3.algolianet.com
ApiError: Invalid syntax for filter: 'price > AND < 100'
Fix: Algolia filter syntax reference:
# Correct syntax
price > 50 AND price < 100 # Numeric range
category:shoes # String equality
NOT category:sandals # Negation
(brand:Nike OR brand:Adidas) # Grouped OR
in_stock = true # Boolean (stored as 0/1)
_tags:featured # Tag filter
#!/bin/bash
echo "=== Algolia Diagnostics ==="
echo "App ID: ${ALGOLIA_APP_ID:-NOT SET}"
echo "Admin key: ${ALGOLIA_ADMIN_KEY:+SET (${#ALGOLIA_ADMIN_KEY} chars)}"
echo ""
echo "=== Connectivity ==="
curl -s -o /dev/null -w "HTTP %{http_code} in %{time_total}s" \
"https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" \
-H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
-H "X-Algolia-API-Key: ${ALGOLIA_ADMIN_KEY}"
echo ""
echo "=== SDK Version ==="
npm list algoliasearch 2>/dev/null || echo "Not installed"
echo "=== Algolia Status ==="
curl -s https://status.algolia.com/api/v2/status.json | jq -r '.status.description' 2>/dev/null
algolia-debug-bundle skillFor comprehensive debugging, see algolia-debug-bundle.