This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/document-engine/troubleshooting/errors-and-warnings/cors.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Document Engine: CORS errors

CORS errors

Markdown version of this page, suitable for AI agents and automation

Cross-origin resource sharing (CORS) errors occur when your browser blocks requests to Document Engine due to security policies. This guide covers common causes and solutions.

Server URL misconfiguration

The most common cause is an incorrect serverUrl in your configuration:

NutrientViewer.load({
  container: "#nutrient-container",
  documentId: "<document_id>",
  authPayload: { jwt: "<jwt>" },
  instant: true,
  serverUrl: "https://<your-document-engine-url>/",
});

The serverUrl must match exactly where your Document Engine instance is running, including the protocol (https://) and trailing slash.

Missing license domains or JWT allowed origins

Your domain must be permitted at both the license level and (if used) in the JWT:

  1. License configuration — Your domain must be listed in your client SDK license and connected to Document Engine. Refer to the domain configuration guide.
  2. JWT allowed_origins claim — If you’re using the allowed_origins claim in your JWT, ensure your frontend domain is included. This claim can only further restrict access within what the license permits. Refer to the backend processing guide for details on JWT configuration.

Proxy server misconfiguration

If you’re running Document Engine behind a reverse proxy (NGINX, Caddy, etc.), the proxy may not be forwarding CORS headers correctly. Configure the proxy to handle preflight requests.

The example below reflects any origin and allows any headers. This is useful for debugging but is overly permissive for production. For production, replace $http_origin with a specific allowlist and restrict headers to only those your application needs.

location / {
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' '$http_origin';
        add_header 'Access-Control-Allow-Headers' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS';
        return 204;
    }
    proxy_pass http://document-engine:5000;
}

Tracing headers from observability tools

Observability tools like Sentry and Datadog inject tracing headers into outgoing HTTP requests; Sentry uses sentry-trace and baggage, while Datadog uses its own x-datadog-* headers (x-datadog-trace-id, x-datadog-parent-id, etc.). These headers aren’t included in Document Engine’s allowed CORS headers, so the browser may block the cross-origin request due to unexpected request headers.

If you’re still seeing CORS errors after checking the above, inspect the https://<your-document-engine-url>/auth request to Document Engine in your browser’s developer tools. Look for a baggage header in the request.

Configure your observability tool to exclude Document Engine URLs from trace propagation. Most tools have a setting like tracePropagationTargets or allowedTracingUrls. Ensure your Document Engine server URL isn’t included.

If you want to maintain tracing for Document Engine requests, use Document Engine’s native OpenTelemetry support instead.