Troubleshoot common errors

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

Resolution

1. Verify the single key is correct and has not expired.
2. Confirm the authentication URL format:

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

3. Confirm the key is from the correct environment (production, staging, or development).
4. Check whether the key was rotated or revoked in the Optimizely portal.
5. Check for whitespace or encoding issues in the key value.

Test with a minimal query to isolate the issue:

query TestAuth {
  _content {
    total
  }
}

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

Resolution

1. Verify your HMAC credentials (App Key and Secret).
2. Confirm the server clock is synchronized. HMAC requires accurate timestamps.
3. Verify the signature calculation:

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

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

For implementation details, see the HMAC authentication documentation.

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

Resolution

1. Verify the token has not expired (check the exp claim).
2. Implement token refresh logic before expiration.
3. Confirm the token is from the correct OIDC provider.
4. Validate that the token audience (aud) matches your Optimizely Graph instance.

For setup instructions, see the OIDC authentication guide.

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

Resolution

1. Verify content is published (not in draft state).
2. Check whether content is excluded from indexing:

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

3. Review synchronization job status:

   • CMS 12: Check scheduled job logs in Admin > Scheduled Jobs.
   • CMS (SaaS): Verify content is published in Visual Builder.

4. Confirm the content type exists in Graph:

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

5. Check for synchronization errors in CMS logs.
6. Verify webhook configurations if using event-driven sync.

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

Resolution

1. Review synchronization configuration:
   • Scheduled jobs: Check frequency and batch size.
   • Event-driven: Verify webhook delivery and processing.
2. Check for failed batches or partial failures in job execution logs.
3. Adjust batch sizes based on content volume.
4. Use content filtering to exclude unnecessary content from sync.
5. Consider event-driven synchronization for near-real-time updates.
6. Check for network or connectivity issues between CMS and the Graph service.

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

Resolution

1. Add the preview parameter to queries:

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

2. Contact Optimizely Support to enable preview functionality. Preview tokens are separate from regular authentication.
3. Verify the content is in "Draft" or "Ready to Publish" status and has been saved.
4. For CMS 12, ensure draft content synchronization is enabled:

services.AddContentGraph(config => {
    config.IncludeDraftContent = true;
    config.IncludeDelayedPublish = true;
});

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

Resolution

1. Verify webhook configuration:

curl https://cg.optimizely.com/api/webhooks?auth=YOUR_KEY
curl https://cg.optimizely.com/api/webhooks/WEBHOOK_ID?auth=YOUR_KEY

2. Confirm the webhook URL is publicly accessible, no firewall rules block incoming requests, and the SSL certificate is valid.
3. Validate the webhook signature in your handler:

public bool ValidateWebhookSignature(
    string payload, string signature, string secret)
{
    var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
    var expectedSignature = Convert.ToBase64String(hash);
    return signature == expectedSignature;
}

4. Check the Graph Portal for webhook delivery status, failed attempts, and retry logs.

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

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";
});

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;
}

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

Resolution

Install the required dependencies:

npm install @apollo/client graphql

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_KEY
documents: './src/**/*.graphql'
generates:
  ./src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typed-document-node

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',
    },
  },
});

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

Resolution

1. Verify the field is configured as searchable in the content type.
2. Common words ("the", "a", "is") are filtered as stopwords. See Stopwords.
3. Use the correct search syntax:

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

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

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

Resolution

1. Confirm the field is configured for faceting in the content type.
2. Verify the field type supports faceting (strings, enums, and similar types).
3. Apply filters correctly alongside facets:

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