Budibase/budibase · error · HTTPError

Project package contains too many docs.

Error message

Project package contains too many docs.

What it means

This error is thrown by extractProjectPackage when validating a Project import package's docs directory. The number of JSON doc files found under the package docs path exceeds MAX_PACKAGE_DOCS, so the server refuses the import to bound resource usage. It is a hard 400 validation limit, not a transient failure.

Source

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

    const [manifest, project, dependencyIndex] = await Promise.all([
      readJsonFile<ProjectPackageManifest>(manifestPath),
      readJsonFile<Project>(projectPath),
      readJsonFile<ProjectPackageDependencyIndex>(dependencyIndexPath),
    ])

    validateManifest(manifest)
    validateProject(project)
    validateDependencyIndexShape(dependencyIndex)

    const docFiles = await fsp
      .access(docsPath)
      .then(() =>
        packageFiles.filter(filePath => filePath.startsWith(docsPath))
      )
      .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
            )

View on GitHub (pinned to a81a902e9a)

Solutions

  1. Trim the docs directory in the package so it contains at most MAX_PACKAGE_DOCS files
  2. Split the content into multiple Project packages and import them separately
  3. Regenerate the package with the official Budibase export, which enforces the doc limit
  4. Increase MAX_PACKAGE_DOCS only if you control the deployment and truly need larger packages

Example fix

// before (package with hundreds of dumped docs)
// docs/row-001.json ... docs/row-900.json
// after: keep only docs the exporter produces, remove bulk row dumps
$ zip -d project.tar.gz 'docs/row-*.json'
Defensive patterns

Strategy: validation

Validate before calling

import { readdir } from "fs/promises"
const docFiles = (await readdir("docs")).filter(f => f.endsWith(".json"))
if (docFiles.length > MAX_PACKAGE_DOCS) throw new Error("Too many docs in package")

Type guard

null

Try / catch

try {
  await sdk.projects.importProject(file)
} catch (e) {
  if (String(e.message).includes("too many docs")) {
    // split the package and retry
  }
}

Prevention

When it happens

Trigger: Calling importProject with a package whose extracted docs directory contains more files than MAX_PACKAGE_DOCS. Typically produced by hand-crafting or tooling-generating a package rather than using the official exporter.

Common situations: Importing a Project package built by scripts that dump an entire workspace DB export into the docs folder; concatenating multiple exports; an old or third-party export tool with different doc limits.

Related errors

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