文档Experience Cloud KCS

数据迁移工具故障排除

最近更新： 2026年8月19日

本文提供了在运行数据迁移工具时可能发生的错误的解决方案。

描述 description

受影响的环境

  • Adobe Commerce版本1
  • Adobe Commerce版本2

问题/症状

  • Source文档/字段未映射
  • 类未在记录中映射
  • 外键约束失败
  • URL重写中存在重复项
  • 实体不匹配
  • 未安装Deltalog

解决方法 resolution

Source文档/字段未映射

错误消息

  • Source文档未映射： < EXTENSION_TABLE>
  • Source字段未映射。 文档： < EXTENSION_TABLE> 。 字段：< EXTENSION_FIELD>

在极少数情况下，消息可能会提及Destination documents或Destination fields，而不是源消息。

原因

Adobe Commerce版本2数据库中不存在某些Adobe Commerce版本1实体，在大多数情况下这些实体来自扩展。

出现此消息是因为数据迁移工具运行内部测试以验证​源 (Adobe Commerce 1)和​目标 (Adobe Commerce 2)数据库之间的表和字段是否一致。

可能的解决方案

  • 从Commerce Marketplace安装相应的Adobe Commerce 2扩展。 如果冲突的数据源自添加自身数据库结构元素的扩展，则相同扩展的Adobe Commerce 2版本可以将此类元素添加到目标(Adobe Commerce 2)数据库中，从而修复问题。

  • 在执行工具时使用-a参数可自动解决错误并阻止迁移停止。

  • 配置工具以忽略有问题的数据。 要忽略数据库实体，请将<ignore>标记添加到map.xml文件中的实体，如下所示：

    code language-none 
    ...
    <source>
        <document_rules>
            ...
            <!-- Ignore `sales_flat_invoice_grid` table -->
            <ignore>
                <document>sales_flat_invoice_grid</document>
            </ignore>
            <!-- Ignore `address_id` field of `sales_flat_order_address` table -->
            <ignore>
                <field>sales_flat_order_address.address_id</field>
            </ignore>
            ...
        </document_rules>
    </source>
    ...

警告：

在通过映射文件忽略实体或使用-a选项之前，请确保在Adobe Commerce 2存储中不需要受影响的数据。

类未在记录中映射

错误消息

类< extension/class_name>未在记录< attribute_id=196>​中映射

原因

在我们的开发人员文档中的EAV迁移步骤期间，在Adobe Commerce 2代码库中找不到Adobe Commerce 1代码库中的类。 在大多数情况下，缺少的类属于扩展。

可能的解决方案

  • 安装相应的Adobe Commerce 2扩展。
  • 忽略导致问题的属性。 为此，将属性添加到eav-attribute-groups.xml.dist文件中的ignore组。
  • 使用class-map.xml.dist文件添加类映射。

外键约束失败

错误消息文本

外键< KEY_NAME>约束在源数据库上失败。 孤立记录ID：< child_table> .<中的< id_1> ， < id_2> field_id>在< parent_table>​中没有引用的记录

原因

child_table的field_id指向的parent_table中缺少数据库记录。

可能的解决方案

从child_table中删除记录（如果不需要这些记录）。

要保留记录，请通过修改数据迁移工具的config.xml禁用Data Integrity Step。

URL重写中有个重复项

There are duplicates in URL rewrites:
Request path: towel.html Store ID: 2 Target path: catalog/product/view/id/10
Request path: towel.html Store ID: 2 Target path: catalog/product/view/id/12

原因

URL重写中的Target path必须由唯一的Request path + Store ID对指定。 此错误报告两个使用相同Request path + Store ID对并具有两个不同Target path值的条目。

可能的解决方案

在config.xml文件中启用auto_resolve_urlrewrite_duplicates选项。

此配置会将哈希字符串添加到URL重写的冲突记录中，并在命令行界面中显示解析结果。

实体不匹配

错误消息

文档中的实体不匹配： <文档> Source： < COUNT_ITEMS_IN_SOURCE_TABLE>目标： < COUNT_ITEMS_IN_DESTINATION_TABLE>

原因

在“Volume Check（卷检查）”步骤中出错。 这意味着文档的Adobe Commerce 2数据库记录数与Adobe Commerce 1中的不同。

当客户在迁移过程中下订单时，会发生丢失记录。

可能的解决方案

以Delta模式运行数据迁移工具以传输增量更改。

未安装Deltalog

错误消息

未安装< TABLE_NAME>的​Deltalog

原因

在对数据进行更改的增量迁移（在我们的开发人员文档中）期间发生此错误。 这意味着在Adobe Commerce 1数据库中找不到deltalog表（前缀为m2_cl_*）。 此工具会在数据迁移 （在我们的开发人员文档中）期间安装这些表，还会安装用于跟踪更改和填充增量表的数据库触发器。

导致该错误的一个原因可能是，您尝试从Live Adobe Commerce 1存储区的​ 副本 ​进行迁移，而不是从Live存储区本身进行迁移。 当您从从未迁移的Adobe Commerce 1实时存储中创建副本时，该副本不包含完成增量迁移所需的触发器和其他增量表，因此迁移失败。 数据迁移工具不会比较AC1和AC2的DB以迁移差异。 相反，该工具使用在首次迁移期间安装的触发器和增量表来执行后续的增量迁移。 在这种情况下，实时Adobe Commerce 1数据库的副本将不包含数据迁移工具用于执行迁移的触发器和删除表。

可能的解决方案

我们建议从Adobe Commerce 1数据库的副本测试迁移过程以修复迁移问题。 修复了副本上的问题后，从实时Adobe Commerce 1数据库中重新开始迁移过程。 这将有助于确保顺利迁移过程。

相关阅读

在Commerce实施行动手册中修改数据库表的最佳实践

recommendation-more-help
experience-cloud-kcs-help-kbarticles