Budibase/budibase · error · HTTPError

Project package dependency index references missing docs.

Error message

Project package dependency index references missing docs.

What it means

The inverse check of error 644: every id listed in dependencyIndex.resources (except the root project id) must have a corresponding doc in the package (imports.ts:765-772). If the index references a resource id for which no doc file exists, import is rejected with 400 because the package is incomplete relative to its own index.

Source

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

    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)) {
      return
    }
    reachable.add(id)
    for (const dependency of dependencyIndex.resources[id]?.dependencies ||
      []) {
      if (dependencyIndex.resources[dependency.id]) {
        visit(dependency.id)
      }
    }

View on GitHub (pinned to a81a902e9a)

Solutions

1. Re-export the full project package so all indexed docs are present.
2. Delete the corresponding entries from dependencyIndex.resources for resources you intentionally removed.
3. Restore the missing doc files into the package, with filenames matching the expected doc path convention.
4. Compare `jq '.resources | keys' dependency-index.json` against the doc ids present in the archive and reconcile both directions.

Example fix

// before: index lists ta_2 but ta_2.json missing
// after: remove from index (or restore ta_2.json)
"resources": { "ta_1": { "dependencies": [] } } // ta_2 entry deleted

const docIds = new Set(pkg.docs.map(d => d._id))
const missing = Object.keys(pkg.dependencyIndex.resources)
  .filter(id => id !== pkg.dependencyIndex.rootProjectId && !docIds.has(id))
if (missing.length) throw new Error(`Index references missing docs: ${missing.join(", ")}`)

try {
  await importProjectPackage(file)
} catch (e) {
  if (e.status === 400 && e.message.includes("references missing docs")) {
    // restore missing doc files or prune index entries, then retry
  } else throw e
}

When it happens

Trigger: Importing a package where dependency-index.json lists resource ids that have no matching doc files — docs were deleted from the archive, files were lost during re-zipping, or the index was generated from a fuller export than the docs shipped.

Common situations: Manually pruning docs (e.g. removing a screen) without updating dependency-index.json; partial/corrupted archives; extracting or copying the package and losing some JSON files; git-ignored or size-limited uploads dropping files.

Related errors

• Project package dependency index does not match project.json
• Project package docs do not match dependency-index.json.
• Project package contains docs not listed in dependency-index
• 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/157d6132e5ed6a6e. Report an issue: GitHub.