Budibase/budibase · error · HTTPError

Project package contains unsupported doc files.

Error message

Project package contains unsupported doc files.

What it means

Thrown by extractProjectPackage when any file inside the Project package's docs directory does not end with .json. Only JSON doc files are permitted there; anything else (text, binaries, archives, CSV) makes the package invalid.

Source

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

      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
            )
          }
          return {
            path: filePath,

View on GitHub (pinned to a81a902e9a)

Solutions

1. Remove all non-.json files from the docs directory in the package and repackage
2. Re-export the Project from Budibase instead of hand-editing the archive
3. Check for hidden files (find docs -type f ! -name '*.json') before zipping
4. Rename files to .json only if their content really is a valid doc; otherwise delete them

Example fix

// before
docs/
  datasources.json
  notes.md          <- unsupported
// after
docs/
  datasources.json

const files = await readdir("docs")
const nonJson = files.filter(f => !f.endsWith(".json"))
if (nonJson.length) throw new Error(`Non-JSON files in docs: ${nonJson.join(", ")}`)

null

try {
  await sdk.projects.importProject(file)
} catch (e) {
  if (String(e.message).includes("unsupported doc files")) {
    // strip non-json entries from the archive and retry
  }
}

When it happens

Trigger: importProject with a package whose docs folder contains non-.json entries — e.g. README.md, .DS_Store, .csv exports, temp files, or subdirectories containing assets added after export.

Common situations: Re-zipping an exported package after OS artifacts (.DS_Store, Thumbs.db) slipped into docs/; editors adding backup files (*.json.bak does NOT match the .endsWith('.json') check and will trigger this); manual edits to the archive.

Related errors

• Project package contains too many docs.
• Project package contains an invalid doc in '${basename(fileP
• Workspace exports cannot be imported as Project packages.
• Invalid bookmark query
• Invalid limit query

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