Algolia Common Errors

Overview

Quick reference for the most common Algolia errors, their root causes, and fixes. All examples use algoliasearch v5 client error types.

Error Reference

1. Invalid Application-ID or API key (403)

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.

---

2. Method not allowed with this API key (403)

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

---

3. Index does not exist (404)

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'

---

4. Rate limit exceeded (429)

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

---

5. Record is too big (400)

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),
  };
}

---

6. Attribute not valid for filtering (400)

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

---

7. RetryError: Unreachable hosts

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

---

8. Invalid filter syntax (400)

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

Quick Diagnostic Script

#!/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

Escalation Path

1. Check status.algolia.com first
2. Collect debug info with algolia-debug-bundle skill
3. Search Algolia Support articles
4. Open support ticket with request ID from error response

Resources

• Algolia Status Page
• API Key Restrictions
• Troubleshooting FAQ

Next Steps

For comprehensive debugging, see algolia-debug-bundle.