schemathesis "Failed to load schema" from URL or file in CI

By Daniel Zoghalchali·Latchkey

schemathesis must load your OpenAPI schema before it can generate tests. It failed to fetch the schema URL (the API is not up, or the path is wrong) or to read the schema file, so no tests run.

What this error means

schemathesis exits with "Failed to load schema" or "Connection refused" for the schema URL, or "No such file or directory" for a schema file path.

Failed to load schema from http://localhost:8000/openapi.json
Connection refused

Common causes

The API serving the schema is not up yet

schemathesis fetched the schema URL before the app started listening, so the connection was refused.

The schema file path or URL is wrong

The --base-url or schema path points at a route or file that does not exist, so the document cannot be loaded.

How to fix it

Wait for the schema endpoint, then run

1. Poll the schema URL until it returns before invoking schemathesis.
2. Confirm the exact schema path (/openapi.json vs /docs/openapi.json).
3. Run schemathesis once the schema loads.

- run: |
    for i in $(seq 1 30); do
      curl -sf http://localhost:8000/openapi.json && break
      sleep 2
    done
- run: schemathesis run http://localhost:8000/openapi.json

Load a schema file with an explicit base URL

When you ship the spec as a file, load the file and give the live base URL for requests.

schemathesis run ./openapi.yaml --base-url http://localhost:8000

How to prevent it

• Gate schemathesis on a readiness check for the schema endpoint.
• Reference the schema by a verified path or a committed file.
• Fail fast with a clear message if the schema never loads.

Frequently asked questions

Related guides

References

• GitHub Actions documentation