{"record":{"id":"cbaa6de1d4856717","repo":"Budibase/budibase","slug":"failed-to-load-openapi-3-document","errorCode":null,"errorMessage":"Failed to load OpenAPI 3 document","messagePattern":"Failed to load OpenAPI 3 document","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/server/src/api/controllers/query/import/sources/openapi3.ts","lineNumber":289,"sourceCode":"      document = await this.validate(document)\n      if (isOpenAPI3(document)) {\n        this.loadDocument(document)\n        return true\n      } else {\n        return false\n      }\n    } catch (err) {\n      return false\n    }\n  }\n\n  load = async (data: string): Promise<void> => {\n    const document = await this.parseData(data)\n    if (isOpenAPI3(document)) {\n      this.loadDocument(document)\n      return\n    }\n    throw new Error(\"Failed to load OpenAPI 3 document\")\n  }\n\n  private loadDocument = (document: OpenAPIV3.Document) => {\n    this.document = document\n    this.serverVariableBindings = {}\n    this.setSecurityHeaders()\n  }\n\n  getServerVariableBindings = () => {\n    const primaryServer = this.getPrimaryServer()\n    if (!Object.keys(this.serverVariableBindings).length) {\n      this.setServerVariableBindings(primaryServer)\n    }\n    const bindings = { ...this.serverVariableBindings }\n    if (this.shouldAddBaseUrlBinding(primaryServer)) {\n      bindings.baseUrl = bindings.baseUrl ?? \"\"\n    }\n    return bindings","sourceCodeStart":271,"sourceCodeEnd":307,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/server/src/api/controllers/query/import/sources/openapi3.ts#L271-L307","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the document declares `openapi: 3.0.x` at the top level (convert Swagger 2.0 with a migration tool like swagger2openapi)","Validate the JSON/YAML file parses cleanly with a linter (e.g. `npx yaml-lint spec.yaml` or `jq . spec.json`)","Confirm you are uploading the spec file itself, not a collection export or wrong file","Use the Swagger import endpoint instead if your document is Swagger 2.0"],"exampleFix":"// before\n// spec.json: { \"swagger\": \"2.0\", \"info\": {...} }\n// after\n// spec.json: { \"openapi\": \"3.0.1\", \"info\": {...}, \"paths\": {...} }","handlingStrategy":"validation","validationCode":"function isOpenApi3Doc(doc) {\n  return doc && typeof doc === \"object\" && typeof doc.openapi === \"string\" && doc.openapi.startsWith(\"3.\") && typeof doc.paths === \"object\"\n}\nif (!isOpenApi3Doc(JSON.parse(specText))) throw new Error(\"Not an OpenAPI 3 document\")","typeGuard":"const isOpenAPI3 = (doc) =>\n  typeof doc === \"object\" && doc !== null &&\n  \"openapi\" in doc && String(doc.openapi).startsWith(\"3.\") &&\n  \"paths\" in doc","tryCatchPattern":"try {\n  await importer.load(data)\n} catch (e) {\n  if (e.message.includes(\"Failed to load OpenAPI 3 document\")) {\n    // fall back to swagger 2 importer or surface a friendly message\n  }\n}","preventionTips":["Run the spec through the Swagger Editor or a validator before importing","Convert Swagger 2.0 specs to 3.0 first","Check the file extension and content type match (JSON vs YAML)","Confirm the top-level `openapi` key exists in your spec"],"tags":["openapi","import","validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}