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. Matching ignores case but compares the whole phrase, not individual words.
- Language matches the query locale, is null (applies to all languages), or is an empty string (neutral locale).
- No more than five active items apply to the same phrase and language. Graph applies at most five pinned items per query.
- targetKey uses the format your schema expects. See Verify the targetKey format.
Verify the targetKey format
Optimizely Graph matches targetKey against the stored content key exactly and does not normalize the value you send. It also accepts any string as a targetKey without returning an error. Optimizely Graph stores an incorrectly formatted key, and the pinned item displays as correctly configured. The item never matches any content. This is a common cause of pinned results that do not appear.
Schema | Query for the key | Expected targetKey format |
|---|---|---|
Native Graph schema, CMS 13 and CMS (SaaS) | _metadata { key } | 32-character GUID with no hyphens, for example 2e684df21e5c4daa8496267cd69485e4 |
Synchronization client schema (CMS 12) | ContentLink { GuidValue } | GUID with hyphens, for example 2e684df2-1e5c-4daa-8496-267cd69485e4 |
Call GET /api/pinned/collections/{id}/items and compare the returned targetKey with the key Graph returns for the same content. Confirm that the two match character for character.
Important
Do not use _id as the targetKey. The _id field joins the content key, the language, and the status with underscores. For example, 2e684df21e5c4daa8496267cd69485e4_en_Published identifies one language and status variant, not the content item. Use the language field on the pinned item to target a specific locale.
Also check for leading or trailing whitespace in targetKey. A padded value does not match.
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.
- More than five matching items – Graph applies only five pinned items per query, keeping the five with the highest priority.
- Unexpected pinned order – A higher priority number ranks higher. Give the item you want first the largest priority value.
- Language mismatch – Match item language to the query locale.
- Inactive collection or item – Set isActive to true. Collections default to isActive: false.
Other common migration differences
Content ID mismatch
Optimizely Search & Navigation uses ContentReference.ID (integer). For pinned items in Optimizely Graph, use _metadata.key as the targetKey on Optimizely CMS 13 and Optimizely CMS (SaaS), or ContentLink.GuidValue on earlier CMS versions. _metadata.key may contain the same GUID value, but use the version-appropriate field as the source.
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. Use a language code such as en, a full CMS locale such as sv-SE where content stores the regional form, null to apply the item to all languages, or an empty string for the neutral locale.
- 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:
Support
Contact Optimizely Support or open an issue on GitHub with questions and feedback.