Budibase/budibase · error

Failed to load OpenAPI 3 document

Error message

Failed to load OpenAPI 3 document

What it means

The OpenAPI3 importer's `load` parses the uploaded document string and validates it with `isOpenAPI3(document)`. If the parsed object is not recognized as a valid OpenAPI 3.x document (missing `openapi` version field or `paths`), it throws this error instead of importing. It guards the REST datasource import flow against non-OpenAPI3 specs such as Swagger 2.0 or arbitrary JSON/YAML.

Source

Thrown at packages/server/src/api/controllers/query/import/sources/openapi3.ts:289

      document = await this.validate(document)
      if (isOpenAPI3(document)) {
        this.loadDocument(document)
        return true
      } else {
        return false
      }
    } catch (err) {
      return false
    }
  }

  load = async (data: string): Promise<void> => {
    const document = await this.parseData(data)
    if (isOpenAPI3(document)) {
      this.loadDocument(document)
      return
    }
    throw new Error("Failed to load OpenAPI 3 document")
  }

  private loadDocument = (document: OpenAPIV3.Document) => {
    this.document = document
    this.serverVariableBindings = {}
    this.setSecurityHeaders()
  }

  getServerVariableBindings = () => {
    const primaryServer = this.getPrimaryServer()
    if (!Object.keys(this.serverVariableBindings).length) {
      this.setServerVariableBindings(primaryServer)
    }
    const bindings = { ...this.serverVariableBindings }
    if (this.shouldAddBaseUrlBinding(primaryServer)) {
      bindings.baseUrl = bindings.baseUrl ?? ""
    }
    return bindings

View on GitHub (pinned to a81a902e9a)

Solutions

1. Verify the document declares `openapi: 3.0.x` at the top level (convert Swagger 2.0 with a migration tool like swagger2openapi)
2. Validate the JSON/YAML file parses cleanly with a linter (e.g. `npx yaml-lint spec.yaml` or `jq . spec.json`)
3. Confirm you are uploading the spec file itself, not a collection export or wrong file
4. Use the Swagger import endpoint instead if your document is Swagger 2.0

Example fix

// before
// spec.json: { "swagger": "2.0", "info": {...} }
// after
// spec.json: { "openapi": "3.0.1", "info": {...}, "paths": {...} }

function isOpenApi3Doc(doc) {
  return doc && typeof doc === "object" && typeof doc.openapi === "string" && doc.openapi.startsWith("3.") && typeof doc.paths === "object"
}
if (!isOpenApi3Doc(JSON.parse(specText))) throw new Error("Not an OpenAPI 3 document")

const isOpenAPI3 = (doc) =>
  typeof doc === "object" && doc !== null &&
  "openapi" in doc && String(doc.openapi).startsWith("3.") &&
  "paths" in doc

try {
  await importer.load(data)
} catch (e) {
  if (e.message.includes("Failed to load OpenAPI 3 document")) {
    // fall back to swagger 2 importer or surface a friendly message
  }
}

When it happens

Trigger: POSTing an API spec to the OpenAPI import endpoint where the parsed document fails the `isOpenAPI3` type guard: a Swagger 2.0 spec (uses `swagger: "2.0"` not `openapi`), a malformed JSON/YAML file, an empty document, or a valid JSON/YAML that is not an API spec at all.

Common situations: Users export a Postman collection or Swagger 2.0 schema and try to import it; file was YAML but truncated or has syntax errors so parseData returns something unrecognizable; pasting the wrong file into the import dialog.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unsupported import data
• Selected endpoint could not be imported
• Invalid import url
• Only HTTP(S) URLs are allowed for query import
• Import url must not contain credentials

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/cbaa6de1d4856717. Report an issue: GitHub.