Troubleshooting CORS

A cross-origin resource sharing (CORS) request occurs when a browser-based application makes a cross-origin call. For example, a Zendesk Apps framework (ZAF) app makes this call to retrieve a shared resource from an external web service.

A CORS request requires certain conditions to work. One condition is that the external service must return the HTTP header Access-Control-Allow-Origin in the response. If the external service doesn't return this header, the system stops the request and displays an error message.

Use this guide to resolve common issues related to the Access-Control-Allow-Origin error message. Below are example error messages:

Failed to load ... No 'Access-Control-Allow-Origin' header

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource ... Reason: CORS header 'Access-Control-Allow-Origin' missing

Failed to load ... Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header present on the requested resource. Origin ... is therefore not allowed access

This article contains the topics below:

Troubleshoot questions

Resolution steps

Alternatives to CORS

Troubleshoot questions

Before you troubleshoot the error, take note of the questions below and identify specific parameters that can help you address the issue:

What's the origin URL of the call? What's the external service URL? The error message sometimes details these URLs.

What do you retrieve and what do you use it for? Do you retrieve a PNG file, a script, CSS, or a font file? This helps you understand the use case and the importance of the external resource.

Which browser and version do you use? Despite the CORS specification standard, different browsers return different error messages.

Does this external resource require authentication? If a redirect occurs, the server might not return the Access-Control-Allow-Origin header, and the call fails. Access the resource URL in incognito mode or a private browser window to test if you can access it under general circumstances.

Can you see the OPTIONS HTTP method in the browser network settings? For custom requests, the browser makes a preflight HTTP call in the CORS request. This preflight call requires specific values. If the OPTIONS call fails, the CORS error appears.

Do you see the HTTP status code 302 before the OPTIONS call? This code indicates a temporary redirect, which can cause the OPTIONS call to fail and trigger a CORS error.

Generate a HTTP Archive (HAR) file. Get a snapshot of the failed call to help you understand and debug the issue.

Resolution steps

Use these solutions and workarounds to resolve the error message:

If you own the external server, modify it to return the Access-Control-Allow-Origin header. If you don't control the external server, coordinate with the server owner.

If you build the app with the Zendesk Apps framework, you can use a backend proxy server through the client.request() call. Use the default value cors:false in the configuration to make requests to the proxy server. Because the proxy service is in the backend, it doesn't need to adhere to the CORS specification standard. However, this isn't always a solution. One limitation is that the proxy service doesn't support the retrieval of binary information from external services.

Sometimes, you can't resolve this issue. Some external resources don't support shared access from a browser-based web app.

Alternatives to CORS

To avoid CORS-related errors in the future, implement these alternatives:

If you use a Zendesk Apps framework app, use the proxy server. Instead of direct fetch() or Asynchronous JavaScript and XML (AJAX) calls, use the client.request() call. This call proxies requests through Zendesk.

Use the Web Widget SDK to embed live chat, messaging, ticket management, Voice (formerly Talk), and help center into your web app. The SDK handles authentication and CORS automatically.

Make application programming interface (API) calls from your backend server instead. A CORS request can fail when you call the Zendesk API directly from a browser. Server-to-server requests don't have CORS restrictions, but browser-based requests do.

Instead of a CORS request, embed the external resource to avoid any cross-origin call. This solution might not work if you don't have the URL of the external resource. It also fails if the resource is too large to store locally, or if the data changes too often. Finally, you can't use this solution if you can't embed the external resource.