Troubleshoot migration issues from Search & Navigation to Graph
This article describes common issues you may encounter when migrating from Optimizely Search & Navigation to Optimizely Graph and explains how to diagnose and resolve them. It also links to official documentation and support channels for 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 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 query includes a pinned object with phrase and collections.
- The phrase value matches the configured phrase.
- The collections value uses the collection key, not the collection ID or GUID.
- The query explicitly specifies the locale parameter.
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 – Graph supports only the top five pinned results.
- 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 includes display options for best bets in its Admin UI. 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. Use one 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:
- Install and configure Optimizely Graph on your siteInstall and configure Optimizely Graph on your site
- Optimizely Search & Navigation documentationOptimizely Search & Navigation documentation
Support
Contact Optimizely Support or open an issue on GitHub with questions and feedback.