---
title: Best practices and troubleshooting
slug: graph/docs/best-practices-and-troubleshooting-saas
docTags: 
createdAt: 2026-07-30T20:30:18.526Z
---

Optimize Optimizely Graph queries and diagnose common integration issues in Optimizely Content Management System (SaaS). This article covers cached templates, single-item result shapes, and troubleshooting steps for authentication, missing data, field errors, and CORS issues.

## Performance best practices

Apply the following techniques to reduce query latency and improve cache efficiency when working with Optimizely Graph in CMS (SaaS).

### Use cached templates

Cached templates store the query shape on the server so repeat requests reuse the parsed query. Enable the `stored` flag in your client to improve query performance.

```csharp
// In Apollo Client
const { data, loading, error } = useQuery(MY_QUERY, {
  variables: { stored: true } // Enable cached templates
});
```

```csharp
var request = new GraphQLRequest 
{ 
    Query = query,
    Variables = new { stored = true } // Enable cached templates
};
```

### Use `item` instead of `items` for single results

When the query targets a single content item, request the `item` field rather than `items`. The `item` field returns one object, which the cache layer fingerprints more efficiently than a single-element array.

The following query has inefficient cache behavior for single results.

```graphql
query GetSingleLandingPage {
  LandingPage(where: { _metadata: { key: { eq: "specific-key" } } }) {
    items {  # Bad: uses items for single result
      _metadata { displayName }
    }
  }
}
```

The following query has efficient cache behavior for single results.

```graphql
  query GetSingleLandingPage {
  LandingPage(where: { _metadata: { key: { eq: "specific-key" } } }) {
    item {  # Good: uses item for single result
      _metadata { displayName }
    }
  }
}
```

## Troubleshoot

Use the following checks to resolve common issues when working with Optimizely Graph and CMS (SaaS).

### Common issues

The following checks address the most frequent failure modes during integration.

**Authentication error (**`401`**)**

- Verify that your API key is correct in the URL parameter or in the header.
- Check that your CMS (SaaS) instance is active and accessible.

**No data returned**

- Verify content is published in [the CMS (SaaS) Visual Builder](docId\:T_BjfxpD8B44vPAL_34nP).
- Query `_Content` first to view available content.
- Verify that content type names match the schema exactly.

**Field not found errors**

- Use `_metadata` for system fields instead of direct properties.
- Content structure differs from CMS 12.
- Explore the schema first with introspection queries.

**CORS issues (browser)**

- Use server-side rendering or API routes for production.
- Configure the proxy in your development environment.

## CMS (SaaS) tips

The following points describe behavior specific to CMS (SaaS) that affects how you author and query content.

- Content types are created through the visual interface in CMS (SaaS).
- Content inherits from `_Content` with `_metadata` fields.
- The platform manages URLs automatically.
- Visual Builder provides real-time preview capabilities.