Troubleshoot Optimizely Opal tools

"Authorization failed" (401)

Your Opti ID token is invalid or missing.

Resolution

Verify you are logged in to CMS 13 with a valid Opti ID session.
Check that the Opti ID token has not expired. Log in to CMS to get a fresh token.

Confirm the EPiServer:Cms:OptimizelyIdentity settings are configured correctly in your application.

{
  "EPiServer": {
    "Cms": {
      "OptimizelyIdentity": {
        "Authority": "https://login.optimizely.com/oauth2/default",
        "InstanceId": "INSTANCE_ID",
        "ClientId": "CLIENT_ID",
        "ClientSecret": "CLIENT_SECRET"
      }
    }
  }
}

Ensure the Opal Chat widget is configured with matching InstanceId.

"Access denied"

You do not have the required CMS permissions for the requested operation.

Resolution

Read operations – You need at least Read access to the content item.
Write operations (create, update, delete, publish) – You need Edit or higher access to the content or its parent container.
Content type operations (list, create, update, delete) – You need a CMS administrator role.
Property group operations – You need a CMS administrator role.
Check your role assignments in CMS Admin > Access Rights.
Verify the content item's access rights are not restricted.

"Content not found"

The specified content GUID does not match a content item in CMS 13.

Resolution

Verify the contentKey is a valid GUID format (for example, c3558e08-00a6-45d0-bfff-5bd2bda3acb5).
Check that the content is not permanently deleted (it may be in the waste basket)
Use paas_cms_list_content_types and the CMS UI to browse for the correct content item.
If working with a specific version, verify the contentVersion number exists.

"Content type not found"

The specified content type key does not exist in CMS 13.

Resolution

Use paas_cms_list_content_types to get the correct content type key.
Content type keys are case-sensitive. Verify the casing is exact.
The content type may be deleted. Check CMS Admin > Content Types.

"Cannot update published version"

The SEO edit tool rejected changes because the target content version is published.

Resolution

Create a draft version of the content before applying SEO edits.
Use the CMS 13 editorial UI to create a new draft, then retry the operation with the updated version number.
The tool returns the correct version number to use after creating a draft.

"Property not found"

A property specified in the update or SEO edit does not exist on the content type.

Resolution

Use the paas_cms_get_content_type_details tool to list all available properties for the content type.
Verify that property names are case-sensitive and match the content type definition exactly.
Metadata properties (system properties such as PageName or PageLink) cannot be updated through the tools.
For SEO edits, verify the actualPropertyNames mapping is correct for your content type.

"No content item exists with the specified key"

The permanent link mapper cannot resolve the content GUID.

Resolution

The GUID may be from a different CMS 13 instance or environment.
Verify you are connected to the correct CMS 13 instance.
The content may be permanently deleted (not just moved to waste basket).

Tool discovery endpoint returns empty or 404

The /opal/discovery endpoint is not responding or is returning no tools.

Resolution

Verify services.AddCmsOpalTools() is called in your service configuration.
Verify endpoints.MapOpalTools("/opal/") is called in your endpoint configuration.
Verify the Opal Tools NuGet package is installed. Run dotnet list package | grep Opal.
Verify the application is running and accessible at the expected URL.
Check the application logs for startup errors related to tool registration.

Opal Chat widget not loading

The Opal Chat widget does not display in the CMS 13 UI.

Resolution

Verify the Optimizely.Cms.OpalChat package is installed.

Check the Opal Chat configuration in appsettings.json or in user secrets.

{
  "Optimizely": {
    "OpalChat": {
      "ServiceUrl": "https://opal-backend.optimizely.com",
      "AppBaseUrl": "https://opal.optimizely.com",
      "SocketUrl": "https://ws.opal.optimizely.com",
      "InstanceId": "YOUR-OPAL-INSTANCE-ID"
    }
  }
}

For local development, use the inte environment URLs.

{
  "ServiceUrl": "https://inte.opal-backend.optimizely.com",
  "AppBaseUrl": "https://inte.opal.optimizely.com",
  "SocketUrl": "https://ws.inte.opal.optimizely.com"
}

Check the browser console for CORS errors. The Opal backend must allowlist your application's origin.

CORS errors when connecting to Opal backend

The browser blocks requests from CMS 13 to the Opal backend due to CORS policy.

Resolution

For local development, the Opal team must add your local origin (for example, https://localhost:5000) to the Opal backend's CORS allowed origins.
Contact the Opal team to allowlist your origin for the appropriate environment (inte, prep, or production).
Verify you are using the correct environment URLs. Do not mix inte and prep URLs.