Troubleshooting

Most API docs issues fall into a few predictable buckets: the spec is invalid, the page metadata does not match the operation, or the playground is sending requests to the wrong place.

​

A generated page is blank

Check the basics first:

1. Validate the OpenAPI file in Swagger Editor or another OpenAPI 3.x validator.
2. Confirm the spec file is actually present in the docs repo.
3. Make sure the page metadata matches the exact method and path.

---
openapi: "GET /documentations"
---

If the spec contains GET /documentation and the page says GET /documentations, Docsalot cannot resolve the operation.

​

The playground calls the wrong backend

Confirm the site-wide API defaults in layout.json.

{
  "api": {
    "baseUrl": "https://docsalot.dev/api/cli/v1",
    "auth": {
      "method": "bearer"
    }
  }
}

For local testing, temporarily switch the base URL to http://localhost:3000/api/cli/v1. A local token will fail against production, and a production token will usually fail against your local database.

If requests still point at an older host, hard refresh the docs preview and clear any persisted playground state in the browser.

​

Browser requests fail locally

If you disable proxying, your API must accept direct browser requests.

Check:

• CORS headers
• bearer token format
• local auth/session state
• whether api.playground.proxy should stay true instead

​

Some operations do not appear in navigation

Look for these causes:

• the navigation group has an explicit pages filter
• the operation is marked x-hidden: true
• the operation is marked x-excluded: true
• the operation fails spec validation

​

Manual and generated pages conflict

Do not define the same endpoint twice. If a route already has a generated OpenAPI page, either keep that page or replace it with one manual MDX page at a different URL.