What causes "Project package doc path does not match '${id}'." in Budibase/budibase?

Rename the file so it exactly matches the doc's `_id`: `mv old.json .json`.

Budibase/budibase · error · HTTPError

Project package doc path does not match '${id}'.

Error message

Project package doc path does not match '${id}'.

What it means

validateDocMatchesPath requires the doc's filename to equal `<_id>.json`. If basename(importedDoc.path) differs from the id derived from the doc body, this HTTPError (400) is thrown — path and content must be consistent so imported docs land at predictable keys.

Source

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

    prefixed(DocumentType.DATASOURCE_PLUS),
  ],
  [ResourceType.TABLE]: [prefixed(DocumentType.TABLE)],
  [ResourceType.ROW_ACTION]: [prefixed(DocumentType.ROW_ACTIONS)],
  [ResourceType.QUERY]: [prefixed(DocumentType.QUERY)],
  [ResourceType.AUTOMATION]: [prefixed(DocumentType.AUTOMATION)],
  [ResourceType.WORKSPACE_APP]: [prefixed(DocumentType.WORKSPACE_APP)],
  [ResourceType.SCREEN]: [prefixed(DocumentType.SCREEN)],
}

const validateDocMatchesPath = (importedDoc: ImportedDoc) => {
  const id = importedDoc.doc._id
  if (!id) {
    throw new HTTPError("Project package contains a doc without an id.", 400)
  }

  const expectedFileName = `${id}.json`
  if (basename(importedDoc.path) !== expectedFileName) {
    throw new HTTPError(`Project package doc path does not match '${id}'.`, 400)
  }

  const validPrefixes = RESOURCE_ID_PREFIXES[importedDoc.resourceType]
  if (!validPrefixes.some(prefix => id.startsWith(prefix))) {
    throw new HTTPError(
      `Project package doc '${id}' does not match resource type '${importedDoc.resourceType}'.`,
      400
    )
  }
}

const remapObjectKeys = <T>(
  value: Record<string, T>,
  idMap: Map<string, string>
) => {
  return Object.fromEntries(
    Object.entries(value).map(([key, nestedValue]) => [
      idMap.get(key) || key,

View on GitHub (pinned to a81a902e9a)

Solutions

Rename the file so it exactly matches the doc's `_id`: `mv old.json <_id>.json`.
Alternatively fix the `_id` inside the JSON to match the existing filename (only if you understand id-prefix semantics).
Re-export the project rather than manually editing package contents.
Add a pre-import check: for every .json, assert `basename === _id + '.json'`.

Example fix

// before
//   ta_abc.json contains { "_id": "ta_abc123", ... }
// after
mv ta_abc.json ta_abc123.json

Defensive patterns

Strategy: validation

Validate before calling

import { basename } from "path"

function docPathMatchesId(path: string, doc: { _id: string }): boolean {
  return basename(path) === `${doc._id}.json`
}
// run for every entry in the docs directory before packaging

Try / catch

try {
  await api.importProjectPackage(file)
} catch (err) {
  if (err?.status === 400 && err.message.startsWith("Project package doc path does not match")) {
    // rename the file to `${_id}.json` (or fix the _id) and repackage
  } else throw err
}

Prevention

Never rename doc files after export
If editing an id, rename the file in the same change
Script a check: basename(path) === `${JSON.parse(content)._id}.json` for all docs
Prefer re-exporting over copying files between packages

When it happens

Trigger: A doc file renamed after export (e.g. `ta_abc.json` containing `_id: "ta_abc123"`), a doc copied to a differently-named file, or a doc whose `_id` was edited without renaming the file.

Common situations: Hand-editing package contents; deduplicating/merging exports by renaming files; scripts that regenerate ids; restoring docs into a package assembled by copying files between exports.

Related errors

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