Failed to load API definition 🔌 API

Swagger UI: Failed to load API definition. Fetch error: Internal Server Error /swagger/v1/swagger.json

Swagger UI couldn’t fetch or parse the OpenAPI document — the generator threw an error, the URL is wrong, or CORS/auth blocks it.

Seen on: REST API

Meaning

In ASP.NET Core (Swashbuckle), duplicate operation IDs/conflicting routes or unsupported types make swagger.json return 500. Behind a proxy the base path may be wrong; on separate domains CORS blocks the fetch.

Common causes

  • Generator exception (duplicate schema/route, missing HTTP method attribute)
  • Wrong spec URL or path base behind a proxy
  • CORS/auth blocking the JSON
  • Invalid YAML/JSON spec

⚡ Quick fix

  1. Open the spec URL directly to see the server error
  2. Fix conflicting actions/schemas (add [HttpGet], CustomSchemaIds)
  3. Set the correct URL/path base for proxies

Detailed fix by platform

C#

  1. builder.Services.AddSwaggerGen(c => c.CustomSchemaIds(t => t.FullName));

How to diagnose

  1. Spec — Response of the JSON URL
  2. Logs — Generator exception
  3. Network — CORS/auth errors

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.