Known limitations and workarounds

Understand platform constraints that affect query design, synchronization behavior, and data modeling. Each limitation includes a recommended workaround.

Content synchronization latency

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 update delays

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.

Large content items

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.

Multi-language content behavior

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

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

Read-only API (no mutations)

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 APIcontent synchronization API.

No real-time subscriptions

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

Workaround Use webhookswebhooks 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.

File and media limits

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.