Budibase/budibase · error · Error

Id ${_id} is not valid for a knowledge base file

Error message

Id ${_id} is not valid for a knowledge base file

What it means

createKnowledgeBaseFile writes a KnowledgeBaseFile doc to the workspace DB. It accepts a caller-supplied `id` (or generates one via docIds.generateKnowledgeBaseFileID). If the resulting _id does not match the knowledge-base-file document ID format (validated by docIds.isKnowledgeBaseFileID), a plain Error is thrown before any DB write. This guards against malformed/foreign IDs being persisted with the KB file doc type.

Source

Thrown at packages/server/src/sdk/workspace/ai/knowledgeBase/files.ts:51

export const createKnowledgeBaseFile = async (
  options: CreateKnowledgeBaseFileOptions
): Promise<WithRequired<KnowledgeBaseFile, "_id">> => {
  const db = context.getWorkspaceDB()
  const {
    id,
    knowledgeBaseId,
    source,
    filename,
    mimetype,
    size,
    uploadedBy,
    objectStoreKey,
    ragSourceId,
  } = options
  const _id = id || docIds.generateKnowledgeBaseFileID(knowledgeBaseId)
  if (!docIds.isKnowledgeBaseFileID(_id)) {
    throw new Error(`Id ${_id} is not valid for a knowledge base file`)
  }

  const doc: RequiredKeys<ToDocCreateMetadata<KnowledgeBaseFile>> = {
    _id,
    knowledgeBaseId,
    source,
    filename,
    mimetype,
    size,
    objectStoreKey,
    ragSourceId: ragSourceId || _id,
    status: KnowledgeBaseFileStatus.PROCESSING,
    uploadedBy,
    errorMessage: undefined,
    processedAt: undefined,
  }

  const { rev } = await db.put(doc)

View on GitHub (pinned to a81a902e9a)

Solutions

1. Generate the ID with docIds.generateKnowledgeBaseFileID(knowledgeBaseId) instead of passing a custom id
2. If passing an id, ensure it was originally produced by generateKnowledgeBaseFileID and matches the expected prefix/format
3. Log the invalid _id and compare with docIds.isKnowledgeBaseFileID output to spot the format mismatch

Example fix

// before
await createKnowledgeBaseFile({ id: myFile.uuid, knowledgeBaseId, ... })
// after
await createKnowledgeBaseFile({ id: docIds.generateKnowledgeBaseFileID(knowledgeBaseId), knowledgeBaseId, ... })

import { docIds } from "@budibase/backend-core"
if (id && !docIds.isKnowledgeBaseFileID(id)) {
  throw new Error(`Refusing to create KB file with invalid id: ${id}`)
}

const isValidKBFileId = (id: string | undefined): id is string =>
  !!id && docIds.isKnowledgeBaseFileID(id)

When it happens

Trigger: Passing options.id that is not a valid knowledge base file ID (e.g. an arbitrary string, an ID generated for another doc type, or one from a different knowledgeBaseId format) into createKnowledgeBaseFile.

Common situations: Reusing an ID from another collection/doc type; constructing IDs manually instead of using docIds.generateKnowledgeBaseFileID; migrating data from an older Budibase version with a different ID scheme.

Related errors

• Error getting status
• Unable to remove doc without a valid _id and _rev.
• Cannot store document without _id field.
• Configuration invalid. Must contain google clientID and clie
• Configuration invalid. Must contain clientID, clientSecret,

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