Six weeks after a headless cutover, a customer emails support asking why a product you discontinued last quarter still shows up when they search your site. Someone checks. The search box works. It returns results instantly, exactly as it always did. It’s just returning them from the last successful crawl of the site you deleted at go-live. The URLs 404, the titles are stale, unpublished pages still rank, and no one filed a bug because, by every surface test, search was fine. This is the most common way enterprise search fails in a headless migration: not with an outage, but with a quiet slide into serving the wrong answers.
eight25 runs enterprise headless migrations for organizations such as NetApp and Sophos, and we treat search re-integration as a discovery deliverable, not a launch-week reconnection. Algolia and Coveo can crawl rendered web pages, while Elasticsearch can be fed through several ingestion patterns, but enterprise headless implementations are usually more dependable when searchable records are created directly from structured CMS content. The work that matters is upstream of the search box: defining the index contract, preserving relevance configuration, choosing the right ingestion pattern, and regression-testing results before cutover.
Why Search Breaks When Nothing Looks Broken
Search survives a migration in the most dangerous way possible: it keeps working. The engine is still running, the API keys are still valid, and the search box still returns ten results in under a hundred milliseconds. What changed is upstream, in the feed that populates the index, and that failure is invisible from the front end.
Enterprise search platforms ultimately operate on indexed records, whether those records are produced by crawling rendered pages or generated directly from CMS data. In the old architecture, a crawler, connector, integration, or publishing process may have created a record containing fields such as title, body, product_category, content_type, locale, and URL. Every facet, filter, and ranking rule was then written against that schema. Replace the monolith with a headless architecture and three things can change at once: the record structure, the events that trigger indexing, and the rendering layer exposed to a crawler. JavaScript-capable crawlers can still index many headless front ends, but the result now depends on rendering speed, extraction rules, routing, and client-side behavior that did not exist in the original integration.
The index does not automatically understand that the content source, route structure, or publication workflow has changed. Depending on the existing configuration, it may continue serving its last populated state, produce incomplete records, or refresh only part of the corpus. That is why the failure often surfaces as stale results, empty facets, 404ing URLs, or a conversion decline rather than as an obvious launch-day outage.
The Content Model Is the Integration
The most expensive misconception in search re-integration is that the integration is the API: the SDK call, the key, the endpoint. It isn’t. The integration is the record schema, and that schema is a direct projection of your content model. When the content model changes in the migration, the search integration changes whether you planned for it or not.
Here’s a simplified Algolia record from a pre-migration product page:
{
"objectID": "sku-4471",
"title": "NetGuard 400 Firewall",
"product_category": "network-security",
"content_type": "product",
"locale": "en-US",
"url": "/products/netguard-400",
"in_stock": true,
"_tags": ["hardware", "enterprise"]
}
Every facet in the UI (product_category), every filter (content_type, locale), every business rule (“boost in_stock:true”) references a field in that record. In the new headless model, product_category might become a referenced taxonomy entry, content_type might be implied by the entry’s model rather than a string field, and locale might move from a field to a separate index entirely. Re-index without mapping those changes and indexing will succeed while every facet returns empty and every ranking rule silently no-ops.
The deliverable that prevents this is an index contract: the exact record schema the new CMS must emit for each content type, with a field-level mapping from the old model to the new one.
| Search record field | Old CMS source | New headless source | Migration action |
|---|---|---|---|
| objectID | Node ID | Entry UID | Remap key; preserve for redirect parity |
| product_category | Text field | Referenced taxonomy entry | Resolve reference to slug at index time |
| content_type | Template name | Content model API ID | Map old template to new model ID |
| locale | Field on record | Separate localized entry | One index (or replica) per locale |
| url | Rendered path | Computed from slug + route | Rebuild URL; must match live redirects |
This table is the artifact that makes search cutover a mapping exercise instead of a guessing game. Without it, someone reverse-engineers the old records under deadline pressure, which guarantees gaps, because the old implementation had undocumented edge cases nobody remembers until a facet breaks.
Relevance Tuning Is the Asset Nobody Backs Up
In a well-designed search architecture, the index should be reproducible from its source data and transformation logic. In practice, teams often discover that some enrichment rules, calculated fields, or mappings exist only inside the old ingestion process. The relevance layer is even easier to overlook because much of it lives in the search platform rather than in the CMS: synonyms such as “laptop” and “notebook,” business rules that promote available products or suppress discontinued SKUs, Coveo query-pipeline rules, and Elasticsearch analyzers or scoring logic. Together, these configurations represent accumulated institutional knowledge that should be exported, documented, and version-controlled before migration work begins.
Before a migration touches anything, that configuration needs to be exported and documented as a relevance inventory:
| Relevance asset | Where it lives | Migration risk | Preservation method |
|---|---|---|---|
| Synonyms & dictionaries | Platform config | Retyped from memory | Export via API, re-import to new index |
| Business rules / boosts | Rules UI | Lost or half-remembered | Export as JSON, re-apply against new schema |
| Query pipelines (Coveo) | Pipeline config | Rebuilt by hand | Export pipeline, re-map to new fields |
| Analyzers (Elastic) | Index mappings | Silently defaulted | Version-control mappings, redeploy |
| ML models (Coveo ART, Algolia) | Trained on old data | Trained on dead URLs | Plan a retraining window on new-site data |
The last row is the one teams underestimate. Behavioral relevance features such as Coveo Automatic Relevance Tuning and Algolia Dynamic Re-Ranking learn from real search activity, including queries, clicks, conversions, content identifiers, and index-level analytics. A migration can interrupt that continuity when object IDs, content IDs, index names, URLs, query pipelines, or analytics instrumentation change. Some history may remain usable when identifiers and analytics relationships are deliberately preserved, but teams should still plan for a validation and adaptation period after launch. Treating the model as automatically portable – or automatically worthless – creates the same risk: a search experience whose relevance changes without anyone measuring why.
Why Headless Architectures Often Favor Push-on-Publish
Many pre-migration search implementations rely on crawling: Algolia Crawler, a Coveo web source, or a custom process that extracts content from rendered pages. That pattern can become less predictable after a headless migration, particularly when important content appears only after client-side rendering, requires API calls, or depends on application state. Modern crawlers can execute JavaScript, but doing so adds rendering time, extraction complexity, and another failure boundary between the CMS record and the search index. A crawl may therefore complete successfully while still producing incomplete, inconsistently structured, or delayed records.
The correct architecture for a headless stack is push-on-publish: the CMS is the source of truth for indexing events, not a crawler guessing at rendered output.
An event-driven pipeline offers three important advantages over scheduled crawling. Published content can become searchable within seconds rather than waiting for the next crawl. Unpublishing can trigger an explicit delete operation instead of relying on a later crawl to infer that a page has disappeared. And index records can be generated from structured CMS fields without depending on the front end to render crawlable HTML. These advantages still require durable webhook delivery, retries, idempotent updates, dead-letter handling, and monitoring; push-on-publish is more controllable, not automatically failure-proof.
When is crawling still reasonable? For a relatively small, server-rendered content site with limited faceting, modest publishing frequency, and no time-sensitive inventory or availability data, Algolia Crawler or a Coveo web source may be entirely adequate. Building and operating a custom push pipeline could add more complexity than value. Push-on-publish becomes more compelling when the site has frequent content changes, real-time states such as stock or pricing, multiple locales, referenced taxonomy, strict deletion requirements, or facets that are more reliably produced from structured CMS fields than extracted from HTML. Match the ingestion pattern to the operating requirements, not to the architecture trend.
Algolia, Coveo, and Elasticsearch Fail Differently
“Re-integrate search” is three different projects depending on the platform, and scoping them the same way is how estimates blow up. Each has a distinct migration center of gravity.
| Dimension | Algolia | Coveo | Elasticsearch (self-managed) |
|---|---|---|---|
| What you migrate | Records, index settings, synonyms, rules, replicas, ingestion logic, and analytics continuity | Sources, mappings, extensions, query-pipeline elements, analytics instrumentation, and ML-model configuration or continuity | Mappings + analyzers + ingest pipeline + cluster |
| Hardest part | Mapping record schema to new model | Preserving source mappings, permissions, query behavior, content identifiers, and ML analytics continuity | You own the whole data pipeline and ops |
| Relevance config | Rules & synonyms (exportable) | Query pipelines (bespoke, per-source) | Custom scoring, analyzers (code-managed) |
| Right fit when | Hosted, low-latency site or product search with application-controlled records and front-end experiences | Enterprise connectors + ML relevance justify cost | Deep control over mappings, analysis, ranking, and ingestion is required, with either internal operational capacity or a managed Elastic deployment |
The table is an orientation anchor, not a verdict. Each platform fits a different operating model. Algolia is often a strong choice when a team wants hosted, low-latency site or product search and can define clean application records. Coveo becomes compelling when search spans multiple enterprise repositories, permissions, query pipelines, and behavior-driven relevance. In that environment, migration planning must protect content identifiers, analytics events, pipeline rules, and model continuity rather than assuming the ML layer will simply follow the new site. Elasticsearch is appropriate when the organization needs extensive control over analysis, mappings, scoring, and ingestion and has the capacity to operate it directly or through a managed Elastic service. For a straightforward marketing site, that flexibility may exceed the actual requirement. eight25 is certified across its core CMS platforms but remains platform-agnostic on search; the recommendation should follow the content model, search use case, governance needs, and operating capacity.
Don’t Cut Over Blind: Shadow Index and Relevance Regression
The final failure mode is the quietest. The new index is built, it returns results, and it goes straight to production with no check on whether those results are right. Relevance degradation doesn’t throw an error. It shows up weeks later as a conversion dip or a rise in “no results” tickets, long after the old configuration is gone and you can’t diff against it.
The discipline that prevents this is the same one that protects SEO equity and analytics through a cutover: build in parallel, validate against a baseline, then switch.
- Pull a representative query set. Export the highest-volume and highest-value queries from the existing platform, often a few hundred for a large site, and include known zero-result, support, product, and navigational queries. This becomes the regression corpus and baseline, so capture it before the old implementation is retired.
- Build a shadow index. Stand up the new index from the new CMS via the push pipeline, fully populated, but not wired to the live search box.
- Run the regression. Query the shadow index and the current production index with the same corpus, then compare result presence, ordering, facets, filters, promoted content, and zero-result behavior. Score each query as equivalent, acceptable change, improvement, or regression, with human review for commercially important searches.
- Cut over on tolerance, not on “it works.” Search is done when the top queries return the right results within an agreed tolerance, not when the box returns something.
Concretely, a relevance regression row looks like this:
| Query | Old top result | Shadow top result | Verdict |
|---|---|---|---|
| “firewall” | NetGuard 400 (in stock) | NetGuard 400 | Match |
| “vpn setup” | Setup guide (2024) | Setup guide (2024) | Match |
| “pricing” | Pricing page | Discontinued SKU | Regression – boost rule lost |
That third row is exactly the failure the whole process exists to catch: a lost business rule, caught in staging instead of in a quarterly review. Index health and query-error monitoring belong in the launch war room next to performance and analytics, and a “search returns zero results or 404s” check belongs in the first-hour rollback criteria. This is the same cutover discipline we used during NetApp’s large-scale enterprise CMS migration: parallel validation, a launch war room, defined rollback criteria, and post-launch hypercare. Search relevance is one more thing that gets validated inside that window instead of being left to a fast-follow. The teams that treat it that way are the ones who never get the discontinued-product email.
Frequently Asked Questions
Why is my site search returning wrong or outdated results after a headless migration?
A stale index is one common cause, but it is not the only one. The search platform may still be serving records from the previous site, or the new ingestion process may be producing incorrect URLs, missing fields, broken facets, incomplete locale data, or ranking rules that reference the old schema. Start by checking index freshness, record counts, source mappings, deletion behavior, and the fields used by filters and ranking. In a headless architecture, rebuilding records directly from the CMS through an event-driven pipeline usually gives the team clearer control over those states than relying only on rendered-page extraction.
How do I reconnect Algolia (or Coveo, or Elastic) to a new headless CMS?
Begin by deciding whether the existing crawler still fits the new architecture. For a simple, server-rendered site, reconnecting and reconfiguring it may be sufficient. For a structured enterprise headless implementation, the more controllable pattern is usually to rebuild the feed: define the record schema each content type must produce, map old fields to the new content model, and send create, update, and delete operations through an event-driven integration. Then export, document, and reapply the relevant synonyms, rules, mappings, query-pipeline elements, and scoring configuration instead of reconstructing them from memory.
Will we lose our search relevance tuning in the migration?
Manual relevance configuration does not need to be lost if it is inventoried before migration. Synonyms, business rules, index settings, mappings, and many query-pipeline elements can be exported, copied, documented, or recreated through configuration-as-code, depending on the platform. Behavioral relevance requires additional care because it depends on analytics, queries, clicks, conversions, record identifiers, content identifiers, and index relationships. Preserve that continuity where the platform allows it, validate instrumentation before launch, and expect the model to adapt as traffic begins flowing through the new experience.
Should search index by crawling or by API push in a headless architecture?
Push-on-publish is often the more controllable default for an enterprise headless implementation because records can be generated directly from structured CMS data and unpublish events can trigger explicit deletion. JavaScript-capable crawlers can still index headless front ends, but they introduce dependencies on rendering, page speed, routing, and extraction rules. Crawling remains reasonable for a smaller, server-rendered content site with limited faceting and no time-sensitive content states, where operating a custom push pipeline would add unnecessary infrastructure.
How do I find an agency that can handle search re-integration in a migration?
Ask one question before signing: who owns the search index contract in the SOW, by name, and is it a crawl or a push-on-publish feed? A partner who treats search as a discovery deliverable, with an index contract, a relevance inventory, and a top-query regression test, is scoping it honestly. “The search vendor handles it” means it’s out of scope, and you’ll discover that at launch.
Planning a Headless Migration With Search Already in Scope?
Most search failures in a migration trace back to a single decision: search was treated as a fast-follow instead of a discovery deliverable. Before you sign a migration SOW, the most useful thing you can do is map the real scope of your search integration, the index contract, the relevance assets that need preserving, and the queries you’ll regression-test against, so nothing gets reverse-engineered under launch pressure. At eight25, we scope search alongside content model and analytics in discovery, before a dollar of build is committed, including the parts most vendors won’t surface until you’re already live.