Budibase/budibase · error · HTTPError

Project import could not remap external table '${entity._id}

Error message

Project import could not remap external table '${entity._id}'.

What it means

During id remapping, external (SQL-backed) table ids are expected to follow the convention '<datasourceId>__<tableName>' (imports.ts:854-874). When remapping a datasource's entities, any entity whose _id is an external table id but does not start with the source datasource's id prefix cannot be safely remapped to the new datasource id, so a 400 HTTPError naming the offending entity is thrown.

Source

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

        )) {
          idMap.set(
            actionId,
            `${VirtualDocumentType.ROW_ACTION}${SEPARATOR}${utils.newid()}`
          )
        }
      }

      if (resourceType === ResourceType.DATASOURCE) {
        const sourceDatasourceId = importedDoc.doc._id!
        const destinationDatasourceId = idMap.get(sourceDatasourceId)!
        const datasource = importedDoc.doc as Datasource
        for (const entity of Object.values(getDatasourceEntities(datasource))) {
          if (!entity._id || !isExternalTableID(entity._id)) {
            continue
          }
          const externalTablePrefix = `${sourceDatasourceId}__`
          if (!entity._id.startsWith(externalTablePrefix)) {
            throw new HTTPError(
              `Project import could not remap external table '${entity._id}'.`,
              400
            )
          }
          idMap.set(
            entity._id,
            `${destinationDatasourceId}${entity._id.slice(sourceDatasourceId.length)}`
          )
        }
      }
    }
  }
}

const bulkInsertDocs = async (
  docs: AnyDocument[],
  insertedDocs: InsertedDocRef[]
) => {

View on GitHub (pinned to a81a902e9a)

Solutions

Re-export the project so external table ids are generated with the correct '<datasourceId>__' prefix.
Rename the offending entity ids in the datasource doc to '<sourceDatasourceId>__<tableName>', matching the datasource's _id in the same package.
Remove the malformed entity from the datasource doc if it does not belong to that datasource.
Verify ids: every entity._id where isExternalTableID holds must begin with the datasource doc's _id followed by '__'.

Example fix

// before (datasource ds_1)
{ "_id": "ds_other__users" }
// after
{ "_id": "ds_1__users" }

Defensive patterns

Strategy: validation

Validate before calling

const dsId = dsDoc._id
for (const entity of Object.values(dsDoc.entities || {})) {
  if (typeof entity._id === "string" && entity._id.includes("__") && !entity._id.startsWith(`${dsId}__`)) {
    throw new Error(`External table ${entity._id} must be prefixed with ${dsId}__`)
  }
}

Type guard

const isRemappableExternalTable = (entity, datasourceId) =>
  typeof entity?._id === "string" && entity._id.startsWith(`${datasourceId}__`)

Try / catch

try {
  await importProjectPackage(file)
} catch (e) {
  if (e.status === 400 && e.message.includes("could not remap external table")) {
    // the offending entity id is quoted in the message; fix its prefix and retry
  } else throw e
}

Prevention

Never rename external table ids inside datasource docs; keep the '<datasourceId>__' convention
Do not copy table entities between datasource docs without re-prefixing their ids
Regenerate datasource docs via export instead of manual edits
Pre-validate that every external table id starts with its datasource's _id + '__'

When it happens

Trigger: Importing a project package containing a datasource doc whose external table entity ids were edited, came from a differently-shaped export, or were copied from another datasource so they lack the '<sourceDatasourceId>__' prefix required for remapping.

Common situations: Hand-edited datasource JSON where table ids were shortened or renamed; packages produced by custom migration tooling; merging table definitions from one datasource into another's doc; older export formats with different external id conventions.

Related errors

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