Diagnosing Swagger UI 'Try it out' Failures: CORS, Auth, Payload, and Server Errors

The same symptom, four different layers

Swagger UI's Try it out button does not call the API itself. It reads the OpenAPI document that generated the page, builds an HTTP request from that document, and hands it to the browser's fetch/XHR layer. Two consequences follow: the request is subject to browser rules (CORS, preflight, mixed content), and the body is whatever example value the spec supplied — not a value you chose.

Start by opening developer tools (F12, or Cmd+Option+I on macOS), selecting the Network tab, enabling the Preserve log option, then clicking Try it out and Execute. Every decision below is based on what that entry shows.

Symptom-to-cause table

Ordered checks

1. Confirm a request was actually sent. If the Network tab stays empty, the problem is in the UI or the document, not the API. Check the Console tab for parse errors and confirm the page loaded a document rather than a stale cached copy.
2. Read the Request URL. Compare scheme, host, port, and base path against where the API actually runs. A spec generated for localhost:8080 will fail silently against a deployed API.
3. Look for a preflight. Requests carrying Authorization or Content-Type: application/json are not simple requests, so the browser sends an OPTIONS request first. If OPTIONS returns 404 or 405, or its response lacks Access-Control-Allow-* headers, the real request never runs.
4. Inspect Request Headers for Authorization. Its absence points at the security scheme or the Authorize dialog, not at the server.
5. Compare the Request Payload against the schema in the OpenAPI document: required properties, types, formats, enums, and nested objects.
6. Read the response body, not just the status code. Validation messages usually name the offending field.
7. For a 500, get the server log for the matching timestamp. This step needs server-side access; without it you are guessing.

Fixes matched to what you found

Blocked by CORS

CORS is enforced by the browser, so the fix belongs on the API server or a proxy in front of it — not in Swagger UI configuration. The response must carry Access-Control-Allow-Origin matching the UI's origin, and the preflight must be answered. The middleware below is illustrative, was not executed for this article, and belongs in the API app before route definitions are registered. Replace the origin with your real Swagger UI host.

// API server, registered before routes
const allowedOrigin = 'https://swagger.example.com';

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', allowedOrigin);
  res.header('Vary', 'Origin');
  res.header('Access-Control-Allow-Methods', 'GET,POST,PUT,PATCH,DELETE,OPTIONS');
  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  if (req.method === 'OPTIONS') return res.sendStatus(204);
  next();
});

Two common mistakes: using a wildcard origin while also sending credentials, which browsers reject, and answering the preflight with a redirect or a body. If you cannot change the API, serve Swagger UI and the API from the same origin through a reverse proxy; that removes the cross-origin condition entirely. Avoid the temptation to disable CORS checks globally — that widens access for every client, not just the UI.

401 Unauthorized

Check the document's securitySchemes and the operation's security block. If the scheme is absent, Swagger UI never shows the Authorize dialog and never attaches a header. If it is present, click Authorize, supply a valid token, and confirm the request now carries the header your scheme defines. Reload the UI after editing the spec; a cached document is a frequent reason the dialog does not appear.

400 Bad Request

The body Swagger UI sends is the spec's example, not your intent. Fix the example in the OpenAPI document so it satisfies the schema, then regenerate the UI. Editing the body in the browser is acceptable for a one-off test, but it hides the spec defect from everyone else using the same document.

500 Internal Server Error

A 500 means the request reached your code. Reproduce it with the same payload using curl or your test suite, then read the server log for the stack trace. If the payload succeeds outside the browser, compare headers — particularly Content-Type, cookies, and any CSRF token the framework expects. If the example value reliably triggers the exception, treat it as a real bug rather than softening the example.

Confirming the fix

Click Execute again and verify three things in the Network tab: the request is present, the status matches what the API documents, and the response body matches the schema. Then repeat with a second operation that uses a different security scheme or content type, because a CORS or auth fix applied to one route may not cover the rest. If you changed the OpenAPI document, hard-reload the page (Ctrl+Shift+R or Cmd+Shift+R) so you are testing the new spec rather than the cached one.

When to escalate

• Headers are correct at the API but missing in the browser: suspect a CDN, WAF, or ingress that strips or rewrites response headers.
• OPTIONS is answered by infrastructure rather than your application: the platform's CORS configuration must change, not your code.
• The UI sends a payload that does not match the document you are reading: confirm which document the UI actually loaded, by checking the URL passed to the UI bundle or the route serving the JSON.
• The API works from curl but never from the browser for any input: compare the full request, including cookies and CSRF headers.

For escalation, collect the Swagger UI version shown in the page footer, the OpenAPI document version and its URL, a Network-tab export of the failing request and response, and the matching server log lines with timestamps.