Algolia Records Missing From Search: A Diagnostic Flow

Recognizable Condition: Dashboard Shows the Record, Search Does Not

You open the Algolia dashboard, find the record by its objectID, and confirm the data is present. Yet the same record never appears in search responses from your application. This pattern usually means the record exists in the index but is being excluded by a configuration layer during the query, or the record was never successfully written to the index you are querying.

Cause and Diagnostic Decision Table

Use this table to map the observed behavior to the most probable cause and the first test to run.

Ordered Checks and Fixes

Run these checks in order. Each step assumes the previous step passed. Stop when the record appears; the fix corresponds to the finding.

Check 1: Confirm the Record Exists in the Intended Index

Open the target index in the Algolia dashboard and search for the record by objectID. If the record is missing from the dashboard, the indexing write never completed. Check the indexing task status in the dashboard or via the API. If the task failed or is still pending, re-push the record and wait for the task to reach a published state before retesting.

Fix: Re-run the indexing operation and monitor the task until it completes. If the record exceeds your plan's size limit, reduce the payload or split the data across multiple records.

Check 2: Strip Filters and Test the Raw Query

Call the search API with an empty query string and explicitly clear filters, facetFilters, and tagFilters. If the record appears, your application is sending restrictive filters. Compare the raw REST response with what InstantSearch returns to isolate client-side defaults.

Fix: Remove the offending filter from the query, or add the excluded attribute to attributesForFaceting if the filter depends on a facet that is not configured.

Check 3: Inspect Secured API Key Restrictions

If the record is absent even with empty filters, inspect the API key. A secured API key is a JSON Web Token (JWT) generated from your search-only API key; it can embed mandatory filters and restrict which indices are accessible. Decode the token payload and look for filters or restrictIndices claims that might exclude the record.

Fix: Issue a new secured API key scoped to the correct index without the unwanted embedded filters. Never use an admin API key in production client code; use it only for this diagnostic comparison.

Check 4: Test Distinct Collapsing

If the record is present but only one of a group of similar records is returned, the distinct parameter may be active. When distinct is enabled, Algolia returns only the best-ranked record for each unique value of the configured distinctAttribute. Retry the query with distinct=false.

Fix: If the record appears with distinct=false, either adjust the distinctAttribute in index settings or omit the distinct parameter from the query.

Check 5: Disable Synonyms and Query Rules

Synonyms and query rules can rewrite the user's query before matching. A rule might replace the query term with something that no longer matches the record, or a synonym might broaden the query in a way that changes ranking. Temporarily disable synonyms and rules through the API, then rerun the search.

Fix: If the record returns, edit or remove the conflicting rule or synonym. Remember that setting changes propagate asynchronously; wait for the operation to complete before retesting.

Check 6: Verify Custom Ranking and Index Targeting

Confirm you are querying the correct index name and not a replica with different ranking. If the record exists but is sorted beyond the first page, review customRanking in the index settings. Custom ranking can push expected records down the result list without excluding them entirely.

Fix: Query the intended index directly, or adjust customRanking so relevant records surface earlier. Use the page or hitsPerPage parameters to page through results during diagnosis.

Concrete Example: Isolating a Filter Exclusion

Suppose a record has category: "electronics" and your frontend sends filters: "category:'books'". The record is excluded. To verify, run the following command from a terminal or API client with your search-only API key:

curl -X GET "https://YOUR_APP_ID.algolia.net/1/indexes/YOUR_INDEX/search?query=test&filters=" \
  -H "X-Algolia-API-Key: YOUR_SEARCH_API_KEY" \
  -H "X-Algolia-Application-Id: YOUR_APP_ID"

Where to run: Any shell or HTTP client with outbound network access. Permissions: A search-only API key is sufficient. Placeholders: Replace YOUR_APP_ID, YOUR_INDEX, and YOUR_SEARCH_API_KEY. Expected check: If the record appears in this empty-filter response, the exclusion is caused by the filter logic in your application. Risk: Removing filters indiscriminately may expose records you intended to restrict.

Escalation Criteria

Escalate to a senior engineer or the search platform team when:

• The indexing task reports success but the record is still absent from the dashboard after the propagation window.
• A secured API key appears to inject filters that are not present in the token payload you decoded.
• Disabling synonyms and rules does not restore the record, and raw API calls with empty filters also fail.
• Plan-specific limits (such as record size or indexing concurrency) are suspected, because these vary by Algolia tier and can change.

Limitations and Final Verification

InstantSearch frontends may apply hidden defaults, such as facet constraints or disjunctive faceting, that raw API calls do not. Always compare the raw REST response with the InstantSearch response before concluding the backend is at fault. Index setting, synonym, and query rule changes propagate asynchronously; wait for the dashboard confirmation before retesting.

Practical check: After applying a fix, verify by running the raw API call with the original query parameters removed one at a time, rather than relying solely on the frontend UI. If the record appears in the raw response but not in the UI, the remaining issue is in client-side widget configuration.