Budibase/budibase · error · HTTPError

Project package contains an invalid doc in '${basename(fileP

Error message

Project package contains an invalid doc in '${basename(filePath)}'.

What it means

Thrown while parsing each .json file in the package docs directory: a doc failed to parse into a record or lacks a string _id field. Every imported doc must be a CouchDB-style object with an _id, so a malformed or empty JSON file aborts the import.

Source

Thrown at packages/server/src/sdk/workspace/projects/backups/imports.ts:1016

      .catch(() => [])

    if (docFiles.length > MAX_PACKAGE_DOCS) {
      throw new HTTPError("Project package contains too many docs.", 400)
    }
    if (docFiles.some(filePath => !filePath.endsWith(".json"))) {
      throw new HTTPError(
        "Project package contains unsupported doc files.",
        400
      )
    }

    const docs = await Promise.all(
      docFiles
        .filter(filePath => filePath.endsWith(".json"))
        .map(async filePath => {
          const doc = await readJsonFile<AnyDocument>(filePath)
          if (!isRecord(doc) || typeof doc._id !== "string") {
            throw new HTTPError(
              `Project package contains an invalid doc in '${basename(filePath)}'.`,
              400
            )
          }
          return {
            path: filePath,
            resourceType: getResourceTypeForDocPath(tmpPath, filePath),
            doc,
          }
        })
    )

    validateDependencyIndex(project, dependencyIndex, docs, manifest)

    return {
      tmpPath,
      manifest,
      project,

View on GitHub (pinned to a81a902e9a)

Solutions

Open the file named in the error and ensure it is a JSON object containing a string _id
Re-download/re-export the package in case the file is truncated or corrupted
Validate every docs/*.json with jq: jq -e 'type == "object" and (._id | type == "string")' file.json
Regenerate the doc from the source workspace rather than hand-repairing it

Example fix

// before (docs/datasource-1.json)
{"name": "My DB"}
// after
{"_id": "datasource_ds_abc123", "name": "My DB"}

Defensive patterns

Strategy: validation

Validate before calling

const isDoc = (v: unknown): v is { _id: string } =>
  typeof v === "object" && v !== null && "_id" in v && typeof (v as { _id: unknown })._id === "string"
for (const f of docFiles) {
  const parsed = JSON.parse(await readFile(join("docs", f), "utf8"))
  if (!isDoc(parsed)) throw new Error(`${f} is not a valid doc`)
}

Type guard

const isAnyDocument = (v: unknown): v is { _id: string } =>
  typeof v === "object" && v !== null && "_id" in v && typeof (v as { _id: unknown })._id === "string"

Try / catch

try {
  await sdk.projects.importProject(file)
} catch (e) {
  const m = String(e.message).match(/invalid doc in '(.+)'/)
  if (m) console.error(`Fix ${m[1]}: must be an object with a string _id`)
}

Prevention

Run jq validation on every docs/*.json before importing
Never hand-edit exported doc files; re-export instead
Verify the archive downloaded fully (checksum/size) before import

When it happens

Trigger: importProject with a package where a docs/*.json file is empty, truncated, an array instead of an object, valid JSON without an _id string property, or not JSON at all despite the .json extension.

Common situations: Manual edits to doc files that dropped _id; partial/corrupted download of the export; scripts writing JSON arrays of docs instead of one object per file; files renamed to .json without converting content.

Related errors

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