Budibase/budibase · error · HTTPError

OpenAPI template must be a YAML or JSON file

Error message

OpenAPI template must be a YAML or JSON file

What it means

`getFileExtension` (used by `fileExtension` during custom REST template upload) accepts only `json`, `yaml`, or `yml` extensions. Anything else throws this 400 HTTPError, because custom REST templates must be OpenAPI documents in JSON or YAML format.

Source

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

    return undefined
  }
  return {
    filepath: upload.filepath,
    filename: upload.originalFilename,
  }
}

const getFileExtension = (
  filename: string
): CustomRestTemplateFileExtension => {
  const extension = filename.split(".").pop()?.toLowerCase()
  if (extension === "json") {
    return "json"
  }
  if (extension === "yaml" || extension === "yml") {
    return "yaml"
  }
  throw new HTTPError("OpenAPI template must be a YAML or JSON file", 400)
}

export const fetch = async (
  ctx: UserCtx<void, FetchCustomRestTemplatesResponse>
) => {
  ctx.body = await sdk.restTemplates.fetch()
}

export const upload = async (
  ctx: UserCtx<
    UploadCustomRestTemplateRequest,
    UploadCustomRestTemplateResponse
  >
) => {
  const file = ctx.request.files?.file
  if (!file || Array.isArray(file)) {
    throw new HTTPError("Exactly one OpenAPI template file is required", 400)
  }

View on GitHub (pinned to a81a902e9a)

Solutions

1. Rename the file to have a .json, .yaml, or .yml extension that matches its content
2. Convert non-OpenAPI formats (WSDL, RAML, Swagger 2.0) to OpenAPI 3 JSON/YAML before upload
3. Re-export the spec from the source tool choosing the OpenAPI 3 YAML/JSON option

Example fix

// before
upload({ file: mySpec.xml })
// after
upload({ file: convertToOpenApi3Yaml(mySpec) }) // mySpec.yaml

const ext = file.name.split(".").pop().toLowerCase()
if (!["json", "yaml", "yml"].includes(ext)) {
  throw new Error(`Unsupported template extension: .${ext}`)
}

try {
  await uploadRestTemplate({ file })
} catch (e) {
  if (e.status === 400 && String(e.message).includes("must be a YAML or JSON file")) {
    // prompt user to pick a .json/.yaml file
  }
}

When it happens

Trigger: Uploading a file whose extension is anything other than .json/.yaml/.yml — e.g. .txt, .xml, .wsdl, .md, or a file with no extension.

Common situations: Users upload a Postman collection (JSON content but named .txt) or a WSDL/XML spec; file downloaded without an extension; macOS renaming files stripping extensions; trying to import RAML or Swagger UI HTML exports.

Related errors

• Exactly one OpenAPI template file is required
• file is required
• Invalid OpenAPI template upload
• Template name is required
• Template description is required

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