Budibase/budibase · critical · HTTPError

Error importing documents

Error message

Error importing documents

What it means

updateWithExport bulk-writes merged documents (new, updated, deleted, metadata) into the workspace DB. If any CouchDB bulkDocs result row contains an error, an HTTPError 500 'Error importing documents' is thrown, leaving the import partially applied (earlier steps are not rolled back by this check).

Source

Thrown at packages/server/src/sdk/workspace/workspaces/import.ts:228

        return false
      }
      const tableId = getTableIdFromRowId(docId)
      return tableId ? existingTableIds.has(tableId) : false
    }

    const filteredUpdate = toUpdate.filter(
      doc => !isRowOfExistingTable(doc._id)
    )
    const filteredDelete = toDelete.filter(
      doc => !isRowOfExistingTable(doc._id)
    )

    // now bulk update documents - add new ones, delete old ones and update common ones
    const updateDocsResult = await workspaceDb.bulkDocs(
      mergeUpdateAndDeleteDocuments(filteredUpdate, filteredDelete, newMetadata)
    )
    if (updateDocsResult.some(r => r.error)) {
      throw new HTTPError("Error importing documents", 500)
    }

    await cache.destroy(getWorkspaceMigrationCacheKey(devId))
    await processMigrations(devId)
  } finally {
    await tempDb.destroy()
  }
}

View on GitHub (pinned to a81a902e9a)

Solutions

1. Retake a fresh export of the source app and retry the import
2. Ensure no concurrent writes to the target workspace during import (perform in a quiet window)
3. Inspect CouchDB logs / the docs in the export for rev conflicts and remove or re-rev them
4. Restore the workspace from a backup taken before the failed import

// pre-check revs against target DB where possible
for (const doc of exportedDocs) {
  if (doc._rev) {
    const existing = await workspaceDb.tryGet(doc._id)
    if (!existing && doc._deleted !== true) delete doc._rev // treat as new
  }
}

try {
  await importToWorkspace(...)
} catch (e) {
  if (e?.message === 'Error importing documents') {
    // restore from backup, take fresh export, retry without concurrent writers
  } else throw e
}

When it happens

Trigger: Any imported document fails validation or conflicts on write — commonly a _rev conflict (doc updated in the target since the export was taken), an invalid doc shape, or a deleted doc whose rev cannot be honored.

Common situations: Importing an old export into a workspace that has since changed; concurrent edits in the dev app during import; exported docs carrying revs that don't exist in the target DB.

Related errors

• Failed to clear project assignments.
• Unable to determine delimiter
• Unable to bulk remove documents: ${res.error}
• TableImportError(errors)
• Unable to remove top level directory - some skeleton files a

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