Known limitations and workarounds

Content synchronization is not instant. Typical latency: 5 to 15 minutes for scheduled sync, 1 to 3 seconds for event-driven sync on small changes (longer for bulk updates).

Workaround
Use event-driven synchronization for near-real-time updates. Set appropriate expectations for content editors. Implement cache-warming strategies for critical content. Use webhooks to trigger front-end rebuilds after sync. See Manage webhooks.

Schema changes (new content types or fields) require synchronization and take several minutes to propagate.

Workaround
Plan schema changes during maintenance windows. Test schema changes in non-production environments first. Wait 5 to 10 minutes after schema changes before deploying dependent code. Verify schema updates using introspection queries before deployment.

Content items larger than 1 MB cause performance issues or timeouts.

Workaround
Paginate large rich text content. Store large media files separately and reference them by URL. Use content references instead of embedding large child content. Split large content items into smaller linked items.

A single content item cannot exceed 29 MB when it syncs to Optimizely Graph. This fixed platform limit is not configurable. When an item exceeds the limit, the integration skips it instead of indexing it. The item never reaches Graph, so it does not appear in the index and queries cannot return it. The sync result reports the skipped item with the error message Skipped indexing document <id> due to being larger than 29 MB. It also returns a 413 Request Entity Too Large status. A skipped item produces a Result.Error response. This sets the sync step to Failed, which causes the scheduled indexing job to report failure. Other items in the run still index. This hard limit differs from the 1 MB threshold, which affects performance rather than blocking indexing.

Workaround
To keep an item under the limit, reduce the number of content items in a content area, flatten deeply nested content-area composition, and use content references instead of embedding child content. The serializer recursively expands nested content-area items up to seven levels. Split large rich text into smaller linked items. If an item already exceeds the limit, edit it so it falls under the limit, or delete the affected version when the error appears on a previously published version.

Fallback language behavior does not match CMS fallback exactly in all scenarios.

Workaround
Review Fallback languages. Query for specific locales explicitly when fallback behavior is critical. Test multi-language scenarios thoroughly in non-production environments.

Optimizely Graph is read-only. It does not support GraphQL mutations for writing or updating data.

Workaround
Use CMS APIs to create or update content. Content changes in CMS synchronize to Graph automatically. For external data, use the content synchronization API.

Optimizely Graph does not support GraphQL subscriptions for real-time push updates.

Workaround
Use webhooks to trigger updates in your application. Implement polling for near-real-time updates (with rate-limiting consideration). Use an event-driven architecture for real-time requirements.

Media files (images, PDFs, and videos) are referenced by URL only. Binary content is not stored in Graph. Media metadata is limited.

Workaround
Store media in a CDN or media library. Reference media URLs in Graph content. Query media metadata fields separately if needed. Use CMS APIs for full media information.