{"record":{"id":"113de52c44c21ab7","repo":"Budibase/budibase","slug":"id-id-is-not-valid-for-a-knowledge-base-file","errorCode":null,"errorMessage":"Id ${_id} is not valid for a knowledge base file","messagePattern":"Id (.+?) is not valid for a knowledge base file","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/server/src/sdk/workspace/ai/knowledgeBase/files.ts","lineNumber":51,"sourceCode":"\nexport const createKnowledgeBaseFile = async (\n  options: CreateKnowledgeBaseFileOptions\n): Promise<WithRequired<KnowledgeBaseFile, \"_id\">> => {\n  const db = context.getWorkspaceDB()\n  const {\n    id,\n    knowledgeBaseId,\n    source,\n    filename,\n    mimetype,\n    size,\n    uploadedBy,\n    objectStoreKey,\n    ragSourceId,\n  } = options\n  const _id = id || docIds.generateKnowledgeBaseFileID(knowledgeBaseId)\n  if (!docIds.isKnowledgeBaseFileID(_id)) {\n    throw new Error(`Id ${_id} is not valid for a knowledge base file`)\n  }\n\n  const doc: RequiredKeys<ToDocCreateMetadata<KnowledgeBaseFile>> = {\n    _id,\n    knowledgeBaseId,\n    source,\n    filename,\n    mimetype,\n    size,\n    objectStoreKey,\n    ragSourceId: ragSourceId || _id,\n    status: KnowledgeBaseFileStatus.PROCESSING,\n    uploadedBy,\n    errorMessage: undefined,\n    processedAt: undefined,\n  }\n\n  const { rev } = await db.put(doc)","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/server/src/sdk/workspace/ai/knowledgeBase/files.ts#L33-L69","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Generate the ID with docIds.generateKnowledgeBaseFileID(knowledgeBaseId) instead of passing a custom id","If passing an id, ensure it was originally produced by generateKnowledgeBaseFileID and matches the expected prefix/format","Log the invalid _id and compare with docIds.isKnowledgeBaseFileID output to spot the format mismatch"],"exampleFix":"// before\nawait createKnowledgeBaseFile({ id: myFile.uuid, knowledgeBaseId, ... })\n// after\nawait createKnowledgeBaseFile({ id: docIds.generateKnowledgeBaseFileID(knowledgeBaseId), knowledgeBaseId, ... })","handlingStrategy":"validation","validationCode":"import { docIds } from \"@budibase/backend-core\"\nif (id && !docIds.isKnowledgeBaseFileID(id)) {\n  throw new Error(`Refusing to create KB file with invalid id: ${id}`)\n}","typeGuard":"const isValidKBFileId = (id: string | undefined): id is string =>\n  !!id && docIds.isKnowledgeBaseFileID(id)","tryCatchPattern":null,"preventionTips":["Always derive IDs via docIds.generateKnowledgeBaseFileID(knowledgeBaseId)","Never pass IDs from other doc types as KB file IDs","Add a unit test asserting the generated ID passes isKnowledgeBaseFileID"],"tags":["validation","document-id","server"],"backgroundTag":"invalid-document-id","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}