Budibase/budibase · error · HTTPError

Exactly one OpenAPI template file is required

Error message

Exactly one OpenAPI template file is required

What it means

The `upload` controller reads `ctx.request.files?.file` and requires exactly one uploaded file: it must exist and must not be an array (multi-file upload). Missing or multiple files throw this 400 HTTPError before any processing occurs.

Source

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

  }
  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)
  }

  const uploadDetails = getUploadDetails(file)
  if (!uploadDetails) {
    throw new HTTPError("Invalid OpenAPI template upload", 400)
  }

  try {
    const name = ctx.request.body.name
    const description = ctx.request.body.description
    if (typeof name !== "string" || !name.trim()) {
      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)

View on GitHub (pinned to a81a902e9a)

Solutions

1. Attach exactly one file under the multipart field name `file` (e.g. `curl -F file=@spec.yaml ...`)
2. Ensure the request uses multipart/form-data encoding
3. Fix client code to append a single file: `formData.append("file", theFile)`
4. Check server/file-upload middleware config so `ctx.request.files` is populated

Example fix

// before
form.append("template", fileInput.files[0])
// after
form.append("file", fileInput.files[0])

const f = formData.get("file")
if (!(f instanceof File) || !f.size) {
  throw new Error("Attach exactly one OpenAPI file under the 'file' field")
}

try {
  await uploadRestTemplate(form)
} catch (e) {
  if (e.status === 400 && String(e.message).includes("Exactly one OpenAPI template file")) {
    // fix the multipart field name / file count and retry
  }
}

When it happens

Trigger: POSTing the upload endpoint without a file field named `file`; attaching multiple files under the same field name (some clients wrap uploads in arrays); using a multipart client that names the field something else (e.g. `template`, `spec`).

Common situations: curl commands forgetting `-F file=@spec.yaml`; frontend FormData appending under the wrong key; API clients sending multiple files to bulk-import; omitting `Content-Type: multipart/form-data` so files never land on `ctx.request.files`.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• OpenAPI template must be a YAML or JSON file
• 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/7166848f91093c49. Report an issue: GitHub.