{"record":{"id":"ba62b73a16b8f65c","repo":"Budibase/budibase","slug":"project-import-could-not-remap-external-table-e","errorCode":null,"errorMessage":"Project import could not remap external table '${entity._id}'.","messagePattern":"Project import could not remap external table '(.+?)'\\.","errorType":"validation","errorClass":"HTTPError","httpStatus":400,"severity":"error","filePath":"packages/server/src/sdk/workspace/projects/backups/imports.ts","lineNumber":864,"sourceCode":"        )) {\n          idMap.set(\n            actionId,\n            `${VirtualDocumentType.ROW_ACTION}${SEPARATOR}${utils.newid()}`\n          )\n        }\n      }\n\n      if (resourceType === ResourceType.DATASOURCE) {\n        const sourceDatasourceId = importedDoc.doc._id!\n        const destinationDatasourceId = idMap.get(sourceDatasourceId)!\n        const datasource = importedDoc.doc as Datasource\n        for (const entity of Object.values(getDatasourceEntities(datasource))) {\n          if (!entity._id || !isExternalTableID(entity._id)) {\n            continue\n          }\n          const externalTablePrefix = `${sourceDatasourceId}__`\n          if (!entity._id.startsWith(externalTablePrefix)) {\n            throw new HTTPError(\n              `Project import could not remap external table '${entity._id}'.`,\n              400\n            )\n          }\n          idMap.set(\n            entity._id,\n            `${destinationDatasourceId}${entity._id.slice(sourceDatasourceId.length)}`\n          )\n        }\n      }\n    }\n  }\n}\n\nconst bulkInsertDocs = async (\n  docs: AnyDocument[],\n  insertedDocs: InsertedDocRef[]\n) => {","sourceCodeStart":846,"sourceCodeEnd":882,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/server/src/sdk/workspace/projects/backups/imports.ts#L846-L882","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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 '__'."],"exampleFix":"// before (datasource ds_1)\n{ \"_id\": \"ds_other__users\" }\n// after\n{ \"_id\": \"ds_1__users\" }","handlingStrategy":"validation","validationCode":"const dsId = dsDoc._id\nfor (const entity of Object.values(dsDoc.entities || {})) {\n  if (typeof entity._id === \"string\" && entity._id.includes(\"__\") && !entity._id.startsWith(`${dsId}__`)) {\n    throw new Error(`External table ${entity._id} must be prefixed with ${dsId}__`)\n  }\n}","typeGuard":"const isRemappableExternalTable = (entity, datasourceId) =>\n  typeof entity?._id === \"string\" && entity._id.startsWith(`${datasourceId}__`)","tryCatchPattern":"try {\n  await importProjectPackage(file)\n} catch (e) {\n  if (e.status === 400 && e.message.includes(\"could not remap external table\")) {\n    // the offending entity id is quoted in the message; fix its prefix and retry\n  } else throw e\n}","preventionTips":["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 + '__'"],"tags":["project-import","id-remapping","datasource"],"backgroundTag":"external-table-id-remap-failed","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}