Budibase/budibase · error · HTTPError

Project package contains docs not listed in dependency-index

Error message

Project package contains docs not listed in dependency-index.json.

What it means

Every document in the package must be declared in dependency-index.json (imports.ts:755-763). After checking each doc's stored path matches its id (validateDocMatchesPath), any doc whose _id is not among the index's resources keys (excluding the root) triggers this 400 error. It guards against orphan or smuggled docs in the archive.

Source

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

  const actualDocIds = new Set(docs.map(doc => doc.doc._id!))
  const expectedDocIds = new Set(
    Object.keys(dependencyIndex.resources).filter(
      id => id !== dependencyIndex.rootProjectId
    )
  )

  if (!dependencyIndex.resources[dependencyIndex.rootProjectId]) {
    throw new HTTPError(
      "Project package docs do not match dependency-index.json.",
      400
    )
  }

  for (const doc of docs) {
    validateDocMatchesPath(doc)
    if (!expectedDocIds.has(doc.doc._id!)) {
      throw new HTTPError(
        "Project package contains docs not listed in dependency-index.json.",
        400
      )
    }
  }

  for (const expectedDocId of expectedDocIds) {
    if (!actualDocIds.has(expectedDocId)) {
      throw new HTTPError(
        "Project package dependency index references missing docs.",
        400
      )
    }
  }

  const reachable = new Set<string>()
  const visit = (id: string) => {
    if (reachable.has(id)) {

View on GitHub (pinned to a81a902e9a)

Solutions

1. Regenerate the package via the export flow so dependency-index.json lists every doc actually shipped.
2. Remove the undeclared doc files from the package, or add corresponding resources entries with their id and dependencies.
3. Diff the archive's doc file ids against `jq '.resources | keys' dependency-index.json` and reconcile.
4. Rebuild the archive from the original export rather than patching an extracted copy.

Example fix

// before: package contains doc ta_99 not in index
// after: either delete ta_99.json or add to dependency-index.json
"resources": { "ta_99": { "dependencies": [] }, ... }

const indexIds = new Set(Object.keys(pkg.dependencyIndex.resources))
const extra = pkg.docs.filter(d => !indexIds.has(d._id))
if (extra.length) throw new Error(`Undeclared docs in package: ${extra.map(d => d._id).join(", ")}`)

try {
  await importProjectPackage(file)
} catch (e) {
  if (e.status === 400 && e.message.includes("not listed in dependency-index.json")) {
    // strip the undeclared docs or regenerate the index, then retry once
  } else throw e
}

When it happens

Trigger: Importing a package that contains extra JSON docs (in the docs directory) with ids absent from dependencyIndex.resources — e.g. files added to the archive after export, stale docs left over from a previous export, or a dependency-index.json that wasn't regenerated when docs changed.

Common situations: Manually adding screens/tables/rows JSON files to an extracted package; re-zipping an older package with extra files; export tooling that appends docs but never updates the index.

Related errors

• Project package dependency index does not match project.json
• Project package docs do not match dependency-index.json.
• Project package dependency index references missing docs.
• Project package resource count mismatch for '${resourceType}
• Project package dependency index is invalid.

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