Troubleshoot migration issues from Search & Navigation to Graph

Go over the common issues you may encounter when migrating from Optimizely Search & Navigation to Optimizely Graph and explains how to diagnose and resolve them. It also provides links to official documentation and support channels if you need additional help.

Content does not sync to Optimizely Graph

If content does not appear in Graph, verify the following:

• Check the Optimizely Graph Full Synchronization scheduled job status and logs.
• Verify that Graph credentials are correct in application configuration.
• Confirm that the content types are enabled and supported for synchronization.
• Ensure the scheduled job has run successfully at least once.

Search results differ between Search & Navigation and Graph

If search results do not match between Optimizely Search & Navigation and Optimizely Graph:

• Compare ranking and relevance behavior, as algorithms differ between products.
• Verify synonym definitions and language configuration.
• Check field mappings and confirm the correct fields are queried.
• Review locale and language routing settings used in queries.

Performance issues

If search performance degrades or response times increase:

• Review query complexity and reduce unnecessary filters or nesting.
• Verify pagination settings and page sizes.
• Confirm caching configuration is enabled and working as expected.
• Contact Optimizely Support if performance issues persist.

HMAC 401 authentication errors

• Verify credentials are correct
• Ensure Base64 encoding is correct: base64(AppKey:Secret)
• Check header format: Authorization: Basic {credentials}
• Confirm environment matches (development/production)
• Test credentials using Swagger or API testing tools

Pinned results do not appear

If pinned (best bet) results configured in Optimizely Search & Navigation do not appear after migrating to Optimizely Graph, use the following steps to systematically diagnose the issue.

1. Verify pinned collection

Use the pinned collections API to confirm that the collection exists and is active.

GET /api/pinned/collections

Verify that:

• The collection exists and uses the expected key
• isActive is set to true

2. Verify pinned items

Retrieve items for the collection.

GET /api/pinned/collections/{id}/items

Verify that:

• Items exist for the expected phrase
• isActive is set to true for each item
• phrase matches the search query exactly
• language matches the query locale (or is an empty string)
• priority is set within the supported range (1–5)

3. Verify query configuration

Confirm that pinned configuration is correctly applied in the Graph query.

Verify that:

• The pinned object is present ({phrase, collections})
• The phrase value matches the configured phrase
• collections uses the collection key, not the collection ID or GUID
• The locale parameter is explicitly specified

4. Verify content availability

Validate that pinned content exists and is published in Optimizely Graph.

Example query:

Content(ids: "GUID") {
  items {
    Name
  }
}

Verify that:

• Content exists in Graph
• Content is published and not expired

Common pinned result issues

Other common migration differences

Content ID mismatch

Optimizely Search & Navigation uses ContentReference.ID (integer), while Optimizely Graph uses GuidValue (GUID).

Solution - Update pinned items to reference GUIDs used by Graph.

Title and description behavior

Optimizely Search & Navigation supports custom Title and Description overrides for pinned results. Optimizely Graph does not support pinned-specific title or description fields.

Solution: Query and render the content’s own Name and Description fields in GraphQL results.

Display styling

Optimizely Search & Navigation supports built-in display options for best bets. Optimizely Graph does not provide display styling controls.

Solution: Implement pinned result styling in the application frontend.

Language handling

• Verify the language field on pinned items ("en", "sv", or empty string)
• Always specify locale in Graph queries. If omitted, results may be returned across all languages

External URLs

Optimizely Graph supports pinned results for internal CMS content only.

Options:

• Create a CMS redirect page.
• Handle external links in application logic.
• Exclude external URLs from migration.

Resources

Use the following resources for additional guidance

• Optimizely Graph Introduction
• Install & Configure Graph
• GraphQL API Guide
• Optimizely Search & Navigation Documentation

Support

For questions or feedback, please contact Optimizely Support or open an issue on GitHub.