Budibase/budibase · error · HTTPError

Unsupported Project doc path '${relPath}'.

Error message

Unsupported Project doc path '${relPath}'.

What it means

getResourceTypeForDocPath maps each doc path inside the package (e.g. <docsDirectory>/<resourceType>/<id>.json) to a resource type. If the first path segment is not the expected PROJECT_DOCS_DIRECTORY, the path does not have exactly 3 segments, or the file lacks a .json extension, this HTTPError (400) is thrown.

Source

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

    }
  } catch (err) {
    throw validationError || new HTTPError("Project package is invalid.", 400)
  }
}

const getResourceTypeForDocPath = (
  tmpPath: string,
  filePath: string
): ResourceType => {
  const relPath = relative(tmpPath, filePath)
  const pathParts = relPath.split(/[\\/]/)
  const [docsDirectory, resourceType] = pathParts
  if (
    docsDirectory !== PROJECT_DOCS_DIRECTORY ||
    pathParts.length !== 3 ||
    !relPath.endsWith(".json")
  ) {
    throw new HTTPError(`Unsupported Project doc path '${relPath}'.`, 400)
  }
  if (
    !resourceType ||
    !ALLOWED_IMPORT_TYPES.has(resourceType as ResourceType)
  ) {
    throw new HTTPError(`Unsupported Project doc path '${relPath}'.`, 400)
  }
  return resourceType as ResourceType
}

const RESOURCE_ID_PREFIXES: Record<ResourceType, string[]> = {
  [ResourceType.PROJECT]: [prefixed(DocumentType.PROJECT)],
  [ResourceType.AGENT]: [prefixed(DocumentType.AGENT)],
  [ResourceType.DATASOURCE]: [
    prefixed(DocumentType.DATASOURCE),
    prefixed(DocumentType.DATASOURCE_PLUS),
  ],
  [ResourceType.TABLE]: [prefixed(DocumentType.TABLE)],

View on GitHub (pinned to a81a902e9a)

Solutions

1. Inspect the archive with `tar -tzf project.tar.gz` and confirm paths match `<docsDirectory>/<resourceType>/<id>.json` exactly (check PROJECT_DOCS_DIRECTORY constant in imports.ts for the expected name).
2. Remove non-doc files (README, .DS_Store, dotfiles, assets) from the archive or move them outside the docs directory.
3. Re-export the project from a compatible Budibase version rather than hand-assembling the package.
4. If the archive has an extra wrapping folder, repackage so the docs directory is at the archive root.

Example fix

// before: paths like
//   my-app/documents/tables/ta_x.json  (wrong dir + extra nesting)
//   notes.txt
// after:
//   documents/tables/ta_x.json
//   documents/screens/screen_x.json
tar -czf project.tar.gz documents/

const PROJECT_DOCS_DIRECTORY = "documents" // check imports.ts for the actual constant

function validateDocPathShape(entryPath: string): boolean {
  const parts = entryPath.split(/[\\/]/)
  return (
    parts[0] === PROJECT_DOCS_DIRECTORY &&
    parts.length === 3 &&
    parts[2].endsWith(".json")
  )
}

try {
  await api.importProjectPackage(file)
} catch (err) {
  if (err?.status === 400 && err.message.startsWith("Unsupported Project doc path")) {
    // inspect `tar -tzf` output; fix directory layout / remove non-JSON files
  } else throw err
}

When it happens

Trigger: A tar entry inside the package whose path doesn't conform to `<docs-dir>/<resourceType>/<docId>.json` — wrong top-level directory name, nested subdirectories (4+ segments), loose files at the root, or non-JSON files such as .txt, .lock or binary assets.

Common situations: Hand-crafted or tool-modified packages that rename the docs folder; extra metadata files (README, .DS_Store) packed into the archive; packages produced by an older/newer export format than the server supports; archives that wrapped files in an extra parent folder.

Related errors

• Project package doc path does not match '${id}'.
• Project package is too large.
• Project package contains a doc without an id.
• Project package doc '${id}' does not match resource type '${
• Project import failed while saving '${failedId}'.

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