Troubleshooting Migration from Optimizely Search & Navigation to Optimizely Graph

This article describes some 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 the application configuration.
Confirm that the content types are enabled and supported for the sync.
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, check the following:

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, check the following:

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

If you receive a 401 authentication error, check the following:

Verify credentials are correct.
Ensure Base64 encoding is correct: base64(AppKey:Secret).
Check header format: Authorization: Basic {credentials}.
Confirm environment matches (development or 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.

Verify pinned collection

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

GET /api/pinned/collections

Verify the following:

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

Verify pinned items

Retrieve items for the collection.

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

Verify the following:

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 through 5).

Verify query configuration

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

Verify the following:

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.

Verify content availability

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

Example query:

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

Verify the following:

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

Common pinned result issues

Collection ID used instead of key – Use collections: ["key"], not ID or GUID.
Priority greater than 5 – Only the top 5 pinned results are supported.
Language mismatch – Match item language to the query locale.
Inactive collection or item – Set isActive to true.

Other common migration differences

Content ID mismatch

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

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.

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.

Implement pinned result styling in the application frontend.

Language handling

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

External URLs

Optimizely Graph supports pinned results for internal CMS content only. You can use any of the following options for external URLs:

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

Resources

See the following resources for additional guidance:

Support

Contact Optimizely Support or open an issue on GitHub with questions and feedback.