Troubleshooting

Most production problems with AACsearch fall into one of seven patterns. This page is a decision tree: start at the top, follow the question that matches, and you'll land at either a fix or a "this is genuinely a support escalation" page with the right diagnostics already gathered.

For escalating after this page, see Support escalation.

The decision tree

Is search returning unexpected results?               → Skip to "Wrong results"
Is search returning 4xx errors?                       → Skip to "Auth / origin / rate-limit errors"
Is search returning 5xx errors?                       → Skip to "Server-side errors"
Is ingest not arriving in search?                     → Skip to "Stale or missing documents"
Are documents arriving but disappearing later?        → Skip to "Documents disappear"
Is a reindex stuck or failed?                         → Skip to "Reindex problems"
Is the dashboard slow or showing wrong numbers?       → Skip to "Dashboard problems"

Wrong results

If the document looks right in the dashboard but searches don't return it, suspect the schema's index: true or the field's absence from query_by. The dashboard stores the document; the engine doesn't necessarily search every field.

Auth / origin / rate-limit errors

Server-side errors

Stale or missing documents

A document you uploaded N seconds ago doesn't appear in search. The ingest pipeline is:

Your application
     │  POST /api/orpc/searchDocument.bulkUpsert
     ▼
SearchIngestBuffer (PostgreSQL row)
     │  Worker picks it up
     ▼
Typesense bulkUpsert
     │  Document searchable
     ▼
Audit + analytics

Where the document might be stuck:

1. Application → API — your request returned 4xx and you didn't retry.
2. API → buffer — buffer row exists but processedAt is null (worker hasn't run yet).
3. Worker → Typesense — buffer row has failedAt and an error message.

Diagnostics:

1. Dashboard → Diagnostics — find the document by docId and read the timeline.
2. Buffer status — the dashboard surfaces this; the procedure is searchIndex.getIngestStatus.
3. Retry — the retry worker re-attempts failed rows up to 5 times. If a row has attempts >= 5 and failedAt set, the message in lastError is your fix.

If everything in the buffer says "succeeded" and the document still doesn't appear, suspect Typesense memory pressure or a swap that completed but didn't pick up recent writes — open a ticket with the document ID.

Documents disappear

A document was searchable yesterday and isn't today. Possibilities, in order:

1. You deleted it. Audit log: action = bulk_delete_documents or delete_documents_by_filter.
2. A reindex dropped it. A reindex pulls from your source of truth. If the document is gone from your source, the reindex won't carry it forward.
3. A connector deleted it. PrestaShop/Bitrix/Shopify connectors mirror your CMS. A delete in the CMS becomes a delete here.
4. Typesense restart from snapshot. Extremely rare. If you suspect this, request a backup verification report.

Action: find the audit log row for the deletion. If you don't see one, it's option 4 — escalate.

Reindex problems

Dashboard problems

When to escalate

If your problem isn't in this tree, or you've followed the tree and reached a "this is genuinely a support issue" leaf, open a ticket per Support escalation. Specifically include:

1. The request ID (x-request-id header) from a failed request.
2. The timestamp in UTC.
3. The organization ID, project ID, and index slug.
4. What you've already checked from this page.

See also

• Status and incidents — check this first
• Monitoring — observe the signals before they become tickets
• Support escalation — what to include in a ticket