Budibase/budibase · error · Error

Failed to load OpenAPI 2 document

Error message

Failed to load OpenAPI 2 document

What it means

OpenAPI2.load parses the raw input and then asserts the resulting document actually is an OpenAPI 2 (Swagger 2.0) document via isOpenAPI2. If the parse succeeds but the document is not swagger '2.0' (e.g. it is an OpenAPI 3 document), load throws 'Failed to load OpenAPI 2 document'.

Source

Thrown at packages/server/src/api/controllers/query/import/sources/openapi2.ts:153

      document = await this.validate(document)
      if (isOpenAPI2(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 (isOpenAPI2(document)) {
      this.loadDocument(document)
      return
    }
    throw new Error("Failed to load OpenAPI 2 document")
  }

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

  getUrl = (): URL | undefined => {
    const scheme = this.document.schemes?.includes("https") ? "https" : "http"
    const basePath = this.document.basePath || ""
    const host = this.document.host

    if (!host) {
      return undefined
    }

    const normalizedBasePath = basePath
      ? basePath.startsWith("/")

View on GitHub (pinned to a81a902e9a)

Solutions

1. Check the document's top-level field: use openapi3.0 importer when it says openapi: 3.x.x
2. Use the auto-detect path (omit type in RestImporter.init) so the correct source is chosen automatically
3. Convert OpenAPI 3 docs to Swagger 2.0 only if you truly must target the 2.0 importer (usually unnecessary)

Example fix

// before
await RestImporter.init(openApi3Yaml, "openapi2.0") // throws
// after
await RestImporter.init(openApi3Yaml, "openapi3.0")
// or:
await RestImporter.init(openApi3Yaml) // auto-detect

function detectSpecVersion(doc: any): "openapi2.0" | "openapi3.0" | null {
  if (doc?.swagger === "2.0") return "openapi2.0"
  if (typeof doc?.openapi === "string" && doc.openapi.startsWith("3")) return "openapi3.0"
  return null
}

const isOpenApi2 = (d: unknown): d is { swagger: "2.0" } =>
  typeof d === "object" && d !== null && (d as any).swagger === "2.0"

try {
  await RestImporter.init(data, "openapi2.0")
} catch (e) {
  if (String(e?.message).includes("Failed to load OpenAPI 2 document")) {
    // spec is probably OpenAPI 3 — retry with openapi3.0 or auto-detect
    await RestImporter.init(data)
  } else throw e
}

When it happens

Trigger: Calling OpenAPI2.load (or RestImporter.init with type 'openapi2.0') on an OpenAPI 3.x document, an AsyncAPI document, or arbitrary JSON/YAML that parses but lacks openapi/swagger: '2.0'.

Common situations: Explicitly selecting 'Swagger 2.0' in the import UI while pasting an OpenAPI 3 spec; a tool exporting 3.0 specs only; assuming any JSON is importable as 2.0.

Related errors

• Unsupported import data
• Selected endpoint could not be imported
• Unsupported method: ${method}
• Empty OpenAPI document
• Failed to load OpenAPI 3 document

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