---
title: Troubleshoot common errors
slug: graph/docs/troubleshoot-common-errors
docTags:
createdAt: 2026-07-30T20:30:20.466Z
---
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](docId\:jCvqClSgbCXru-STGbjCa).
## 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**
1. Verify the single key is correct and has not expired.
2. Confirm the authentication URL format:
```text
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:
```graphql
query TestAuth {
_Content {
total
}
}
```
**HMAC authentication failure**
**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:
```csharp
var timestamp = DateTimeOffset.UtcNow();
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](docId\:sNcLLcLYgWv_QVb0Mtqus).
**Bearer token (OIDC) issues**
**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](docId\:sNcLLcLYgWv_QVb0Mtqus).
## 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**
1. Verify content is published (not in draft state).
2. Check whether content is excluded from indexing:
```csharp
// 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:
```graphql
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.
**Content synchronization delays**
**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.
## 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**
1. Add the preview parameter to queries:
```graphql
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:
```csharp
services.AddContentGraph(config => {
config.ContentVersionSyncMode = ContentVersionSyncMode.DraftAndPublishedOnly;
});
```
## Webhook issues
Diagnose webhook delivery failures and validate endpoint configuration. For webhook management, see [Manage webhooks](docId\:mpRrgEOwxpyzgXW1PNeOG).
**Webhooks not firing**
**Symptoms**
Webhook endpoint does not receive notifications, synchronization completes but no webhook calls arrive, missing webhook events.
**Resolution**
1. Verify webhook configuration:
```bash
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.
```text
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")
```
2. 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](docId\:Jb6E4MafgLYifo6YMn2V9).
**Package installation fails**
**Symptoms**
`Unable to find package EPiServer.ContentGraph` error when installing NuGet packages.
**Resolution**
Add the Optimizely NuGet source:
```xml
```
Then install the packages:
```bash
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:
```csharp
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()`:
```csharp
public async Task> GetArticlesAsync()
{
var result = await _graphClient.Query()
.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:
```bash
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:
```bash
npm install --save-dev @graphql-codegen/cli @graphql-codegen/typescript
```
```yaml
# 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:
```javascript
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 search](docId\:aM0WpNsNXe_n26IhkX5sG).
**Search not returning expected results**
**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. Use the correct search syntax:
```graphql
query SearchArticles {
ArticlePage(
where: {
_fulltext: {
match: "technology innovation"
}
}
) {
items {
Name
TeaserText
}
}
}
```
3. 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**
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:
```graphql
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