{"record":{"id":"00e96c03f8d03bb4","repo":"Budibase/budibase","slug":"failed-to-load-openapi-2-document","errorCode":null,"errorMessage":"Failed to load OpenAPI 2 document","messagePattern":"Failed to load OpenAPI 2 document","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/server/src/api/controllers/query/import/sources/openapi2.ts","lineNumber":153,"sourceCode":"      document = await this.validate(document)\n      if (isOpenAPI2(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 (isOpenAPI2(document)) {\n      this.loadDocument(document)\n      return\n    }\n    throw new Error(\"Failed to load OpenAPI 2 document\")\n  }\n\n  private loadDocument = (document: OpenAPIV2.Document) => {\n    this.document = document\n    this.setSecurityHeaders()\n  }\n\n  getUrl = (): URL | undefined => {\n    const scheme = this.document.schemes?.includes(\"https\") ? \"https\" : \"http\"\n    const basePath = this.document.basePath || \"\"\n    const host = this.document.host\n\n    if (!host) {\n      return undefined\n    }\n\n    const normalizedBasePath = basePath\n      ? basePath.startsWith(\"/\")","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/server/src/api/controllers/query/import/sources/openapi2.ts#L135-L171","documentation":"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'.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Check the document's top-level field: use openapi3.0 importer when it says openapi: 3.x.x","Use the auto-detect path (omit type in RestImporter.init) so the correct source is chosen automatically","Convert OpenAPI 3 docs to Swagger 2.0 only if you truly must target the 2.0 importer (usually unnecessary)"],"exampleFix":"// before\nawait RestImporter.init(openApi3Yaml, \"openapi2.0\") // throws\n// after\nawait RestImporter.init(openApi3Yaml, \"openapi3.0\")\n// or:\nawait RestImporter.init(openApi3Yaml) // auto-detect","handlingStrategy":"validation","validationCode":"function detectSpecVersion(doc: any): \"openapi2.0\" | \"openapi3.0\" | null {\n  if (doc?.swagger === \"2.0\") return \"openapi2.0\"\n  if (typeof doc?.openapi === \"string\" && doc.openapi.startsWith(\"3\")) return \"openapi3.0\"\n  return null\n}","typeGuard":"const isOpenApi2 = (d: unknown): d is { swagger: \"2.0\" } =>\n  typeof d === \"object\" && d !== null && (d as any).swagger === \"2.0\"","tryCatchPattern":"try {\n  await RestImporter.init(data, \"openapi2.0\")\n} catch (e) {\n  if (String(e?.message).includes(\"Failed to load OpenAPI 2 document\")) {\n    // spec is probably OpenAPI 3 — retry with openapi3.0 or auto-detect\n    await RestImporter.init(data)\n  } else throw e\n}","preventionTips":["Check the spec's top-level key (swagger: 2.0 vs openapi: 3.x) before choosing the importer type","Prefer omitting the explicit type and let RestImporter.init auto-detect","Don't assume all JSON/YAML API descriptions are Swagger 2.0"],"tags":["openapi","version-mismatch","validation"],"backgroundTag":"unsupported-spec-version","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}