Budibase/budibase · error · HTTPError

File must contain a valid OpenAPI schema

Error message

File must contain a valid OpenAPI schema

What it means

This 400 HTTPError wraps any failure while parsing the uploaded file as an OpenAPI 2.0 (Swagger) or 3.0 document. createImporter builds a format importer from the file contents; if parsing fails or the detected import source is anything other than openapi2.0/openapi3.0 (e.g. Postman, curl, GraphQL collections), the original error is discarded and this generic 400 is raised.

Source

Thrown at packages/server/src/api/controllers/restTemplate.ts:90

      throw new HTTPError("Template name is required", 400)
    }
    if (typeof description !== "string") {
      throw new HTTPError("Template description is required", 400)
    }

    const fileExtension = getFileExtension(uploadDetails.filename)
    const data = await readFile(uploadDetails.filepath, "utf8")
    let importer
    let info
    try {
      importer = await createImporter({ data })
      const source = importer.getSource().getImportSource()
      if (source !== "openapi2.0" && source !== "openapi3.0") {
        throw new Error("Unsupported OpenAPI source")
      }
      info = importer.getInfo()
    } catch {
      throw new HTTPError("File must contain a valid OpenAPI schema", 400)
    }

    ctx.body = {
      template: await sdk.restTemplates.create({
        name,
        description,
        data,
        fileExtension,
        operationsCount: info.endpoints.length,
      }),
    }
  } finally {
    await unlink(uploadDetails.filepath).catch(() => {})
  }
}

export const update = async (
  ctx: UserCtx<

View on GitHub (pinned to a81a902e9a)

Solutions

1. Validate the file locally against the OpenAPI 2.0 or 3.0 schema before uploading (e.g. with a swagger/openapi validator)
2. Fix JSON/YAML syntax errors in the spec; ensure required fields like openapi/swagger, info and paths are present
3. Convert unsupported formats (Postman, 3.1) to OpenAPI 3.0 before uploading
4. Confirm the file extension is .json, .yaml or .yml so the correct parser is selected

Example fix

// before
openapi: 3.1.0   # unsupported version
// after
openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
paths: {}

const spec = yamlOrJson.parse(fileContent)
if (!spec || !(spec.openapi?.startsWith("3.0") || spec.swagger === "2.0")) {
  throw new Error("File is not an OpenAPI 2.0/3.0 document")
}

const isOpenAPI = (v: unknown): v is { openapi?: string; swagger?: string; paths: Record<string, unknown> } =>
  typeof v === "object" && v !== null &&
  ("openapi" in v || "swagger" in v) && "paths" in v

try {
  await uploadTemplate(form)
} catch (e) {
  if (e?.status === 400 && /valid OpenAPI schema/.test(e?.message)) {
    // validate the spec locally and report parse errors to the user
  } else throw e
}

When it happens

Trigger: Uploading a file whose contents are not valid JSON/YAML; uploading a valid file in an unsupported collection format (e.g. Postman v2.1 export); uploading a file with a .json/.yaml extension but malformed or non-OpenAPI schema content.

Common situations: Exporting specs from API tools that produce non-OpenAPI formats; hand-edited specs with YAML syntax errors; OpenAPI 3.1 documents rejected by the older parser; uploading a README or CSV renamed to .json.

Related errors

• Invalid bookmark query
• Invalid limit query
• Limit query must be between 1 and 100
• Invalid ${queryName} query
• Invalid environment query

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