Troubleshoot common errors

18 min

Resolve the most frequent Optimizely Graph errors by matching symptoms to solutions. Expand any item to see the cause and resolution steps. Where a topic has dedicated documentation, the answer links to the canonical article for full details. For GraphQL query errors, performance issues, and debugging techniques, see Debug GraphQL queries.

Authentication errors

Verify credentials, token validity, and endpoint configuration to resolve authentication failures.

Single-key authentication failure

Symptoms HTTP 401 Unauthorized responses, Invalid authentication credentials error, queries fail without processing.

Resolution

Verify the single key is correct and has not expired.

Confirm the authentication URL format:

https://cg.optimizely.com/content/v2?auth=YOUR_SINGLE_KEY

Confirm the key is from the correct environment (production, staging, or development).

Check whether the key was rotated or revoked in the Optimizely portal.

Check for whitespace or encoding issues in the key value.

Test with a minimal query to isolate the issue:

query TestAuth {
  _Content {
    total
  }
}

HMAC authentication failure

Symptoms HTTP 401 or 403 responses, HMAC signature verification failed error, timestamp-related errors.

Resolution

Verify your HMAC credentials (App Key and Secret).

Confirm the server clock is synchronized. HMAC requires accurate timestamps.

Verify the signature calculation:

var timestamp = DateTimeOffset.UtcNow();
var signature = CalculateHmacSignature(appKey, secret, timestamp);

Test with a known-good HMAC implementation before debugging custom code.

For implementation details, see the HMAC authentication documentationHMAC authentication documentation.

Bearer token (OIDC) issues

Symptoms HTTP 401 Unauthorized, Token expired or Invalid token errors, intermittent authentication failures.

Resolution

Verify the token has not expired (check the exp claim).

Implement token refresh logic before expiration.

Confirm the token is from the correct OIDC provider.

Validate that the token audience (aud) matches your Optimizely Graph instance.

For setup instructions, see the OIDC authentication guideOIDC authentication guide.

Content synchronization issues

Diagnose why published content does not appear in Graph queries or takes longer than expected to sync.

Content not appearing in Graph

Symptoms Published content does not display in GraphQL queries, content exists in CMS but not in Graph, synchronization delays longer than expected.

Resolution

Verify content is published (not in draft state).

Check whether content is excluded from indexing:

// CMS 12: check for exclusion
if (content is IExcludeFromSearch excludeFromSearch &&
    excludeFromSearch.ExcludeFromSearch)
{
    // Content is excluded from Graph
}

Review synchronization job status:

CMS 12: Check scheduled job logs in Admin > Scheduled Jobs.

CMS (SaaS): Verify content is published in Visual Builder.

Confirm the content type exists in Graph:

query CheckContentType {
  __type(name: "YOUR_CONTENT_TYPE_NAME") {
    name
    fields {
      name
    }
  }
}

Check for synchronization errors in CMS logs.

Verify webhook configurations if using event-driven sync.

Content synchronization delays

Symptoms Content takes longer than expected to appear in Graph, updates do not reflect immediately, inconsistent synchronization times.

Resolution

Review synchronization configuration:

Scheduled jobs: Check frequency and batch size.

Event-driven: Verify webhook delivery and processing.

Check for failed batches or partial failures in job execution logs.

Adjust batch sizes based on content volume.

Use content filtering to exclude unnecessary content from sync.

Consider event-driven synchronization for near-real-time updates.

Check for network or connectivity issues between CMS and the Graph service.

Preview and draft content issues

Access draft and unpublished content through Graph preview queries.

Draft content not appearing in queries

Symptoms Published content displays but draft content does not, preview tokens do not work, content displays in CMS but not in Graph queries.

Resolution

Add the preview parameter to queries:

query GetDraftContent {
  ArticlePage(
    locale: en
    preview: true
  ) {
    items {
      Name
      Status
      _metadata {
        published
      }
    }
  }
}

Contact Optimizely Support to enable preview functionality. Preview tokens are separate from regular authentication.

Verify the content is in "Draft" or "Ready to Publish" status and has been saved.

For CMS 12, ensure draft content synchronization is enabled:

services.AddContentGraph(config => {
    config.ContentVersionSyncMode = ContentVersionSyncMode.DraftAndPublishedOnly;
});

Webhook issues

Diagnose webhook delivery failures and validate endpoint configuration. For webhook management, see Manage webhooks.

Webhooks not firing

Symptoms Webhook endpoint does not receive notifications, synchronization completes but no webhook calls arrive, missing webhook events.

Resolution

Verify webhook configuration:

curl -X GET https://cg.optimizely.com/api/webhooks

Using Authorization: The acceptable authorization methods are Basic and epi-hmac:

Basic:

Username – AppKey

Password – Secret

Both the username and password must be encoded with the Base64 algorithm, so the header is Authorization: Basic base64(AppKey:Secret).

epi-hmac – The AppKey and the Secret are signed by the HMAC algorithm.

var crypto = require("crypto-js");
var sdk = require('postman-collection');
// This script uses 2 variables.
//
// EPTSKey
// EPTSSecret
//
var method = pm.request.method;
var key = pm.variables.get("EPTSKey");
var secret = CryptoJS.enc.Base64.parse(pm.variables.get("EPTSSecret"));
var target = new sdk.Url(request.url).getPathWithQuery();
var timestamp = (new Date()).getTime();
var nonce = Math.random().toString(36).substring(7);
var body = "";
if( pm.request.body )
{
    body = pm.request.body.raw;
}
var bodybase64 = crypto.MD5(body).toString(CryptoJS.enc.Base64);
var hmac = crypto.HmacSHA256(key + method + target + timestamp + nonce + bodybase64, secret);
var base64hmac = CryptoJS.enc.Base64.stringify(hmac);
var header = "epi-hmac " + key + ":" + timestamp +":" + nonce + ":" + base64hmac;
pm.request.headers.add(header, "Authorization")

Confirm the registered webhook URL is publicly accessible, no firewall rules block incoming requests, and the SSL certificate is valid.

.NET Source SDK (CMS 12) issues

Resolve package installation, configuration, and runtime errors in the Optimizely Graph .NET Source SDK.NET Source SDK.

Package installation fails

Symptoms Unable to find package EPiServer.ContentGraph error when installing NuGet packages.

Resolution

Add the Optimizely NuGet source:

<packageSources>
  <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  <add key="Optimizely" value="https://nuget.optimizely.com/feed/packages.svc/" />
</packageSources>

Then install the packages:

dotnet add package EPiServer.ContentGraph
dotnet add package EPiServer.ContentGraph.Cms

Configuration not loading

Symptoms Graph client fails to initialize, missing or null configuration values at runtime.

Resolution

Verify Startup.cs reads the configuration correctly:

services.AddContentGraph(options =>
{
    options.AppKey = configuration["Optimizely:ContentGraph:AppKey"];
    options.Secret = configuration["Optimizely:ContentGraph:Secret"];
    options.GatewayAddress = "https://cg.optimizely.com";
});

Query returns null or empty results

Symptoms Graph queries return null or an empty collection despite content existing in the CMS.

Resolution

Verify async and await usage and call .ToListAsync():

public async Task<IEnumerable<ArticlePage>> GetArticlesAsync()
{
    var result = await _graphClient.Query<ArticlePage>()
        .Where(x => x.Status.Equals("Published"))
        .ToListAsync();
    return result;
}

JavaScript and TypeScript SDK issues

Resolve module installation, type generation, and caching errors in JavaScript and TypeScript Graph clients.

Module import errors

Symptoms Cannot find module '@apollo/client' error when building or running the application.

Resolution

Install the required dependencies:

npm install @apollo/client graphql

TypeScript type definitions missing

Symptoms Could not find a declaration file for module error in TypeScript projects.

Resolution

Generate types from the Graph schema:

npm install --save-dev @graphql-codegen/cli @graphql-codegen/typescript

# codegen.yml
schema: https://cg.optimizely.com/content/v2?auth=YOUR_SINGLE_KEY
documents: './src/**/*.graphql'
generates:
  ./src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typed-document-node

Apollo Client cache returning stale data

Symptoms Queries return outdated content, UI does not reflect recent content changes.

Resolution

Configure cache policies and use cache-and-network fetch policy:

const client = new ApolloClient({
  uri: 'https://cg.optimizely.com/content/v2?auth=YOUR_KEY',
  cache: new InMemoryCache({
    typePolicies: {
      ArticlePage: {
        keyFields: ['_metadata', ['key']],
      },
    },
  }),
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'cache-and-network',
    },
  },
});

Search and facets issues

Fix search relevance problems and facet configuration errors. For search syntax details, see Full-text searchFull-text search.

Search not returning expected results

Symptoms Search returns no results when results are expected, irrelevant results returned, search ignores certain terms.

Resolution

Verify the field is configured as searchable in the content type.

Use the correct search syntax:

query SearchArticles {
  ArticlePage(
    where: {
      _fulltext: {
        match: "technology innovation"
      }
    }
  ) {
    items {
      Name
      TeaserText
    }
  }
}

Start with simple single-word searches and add complexity gradually to isolate the issue.

Facets not working correctly

Symptoms Facet counts are incorrect, missing facet values, facets do not update with filters.

Resolution

Confirm the field is configured for faceting in the content type.

Verify the field type supports faceting (strings, enums, and similar types).

Apply filters correctly alongside facets:

query FilteredFacets($category: String) {
  ArticlePage(
    where: { Category: { eq: $category } }
  ) {
    items { Name }
    facets {
      Tags {
        name
        count
      }
    }
  }
}

Quick diagnosis checklist

Use this checklist when diagnosing any Optimizely Graph issue.

Authentication

Credentials are correct and have not expired

Using the correct authentication method (single-key, HMAC, or OIDC)

Credentials are from the correct environment

Authentication header or parameter is properly formatted

Network

Graph API endpoint is accessible

No firewall or proxy blocking requests

CORS is handled through a server-side proxy for browser clients

SSL certificates are trusted

Query

Query syntax is valid (no missing brackets or quotes)

Field names are spelled correctly (case-sensitive)

Fields exist in the schema (verified in GraphiQL)

Using correct filter operators

Query depth is five levels or fewer

Content

Content is published in CMS (not in draft state)

Content type is synchronized to Graph

Synchronization job ran without errors

Content is not excluded from indexing

Sufficient time has passed since the last publish

SDK and integration

SDK version is up to date

Dependencies are installed

Configuration settings are correct

Async and await are used correctly (.NET)

Error handling is implemented