|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +group: migration |
| 4 | +subgroup: F_troubleshooting |
| 5 | +title: Troubleshooting |
| 6 | +menu_title: Troubleshooting |
| 7 | +menu_node: parent |
| 8 | +menu_order: 6 |
| 9 | +version: 2.0 |
| 10 | +github_link: migration/migration-troubleshooting.md |
| 11 | +--- |
| 12 | + |
| 13 | +## Common error messages |
| 14 | + |
| 15 | +This section is about the errors that might occur when you run the Data Migration Tool, and how to deal with them. |
| 16 | + |
| 17 | +### Source documents/fields not mapped |
| 18 | + |
| 19 | +{% highlight xml %} |
| 20 | +Source documents are not mapped: <EXTENSION_TABLE> |
| 21 | +{% endhighlight %} |
| 22 | + |
| 23 | +{% highlight xml %} |
| 24 | +Source fields are not mapped. Document: <EXTENSION_TABLE>. Fields: <EXTENSION_FIELD> |
| 25 | +{% endhighlight %} |
| 26 | + |
| 27 | +In rare cases, the message might mention `Destination documents` or `Destination fields` instead of source ones. |
| 28 | + |
| 29 | +#### Explanation |
| 30 | + |
| 31 | +Some Magento 1 entities (in most cases, coming from extensions) do not exist in the Magento 2 database. |
| 32 | + |
| 33 | +This message appears because the Data Migration Tool runs internal tests to verify that tables and fields are consistent between *source* (Magento 1) and *destination* (Magento 2) databases. |
| 34 | + |
| 35 | +#### Possible solutions |
| 36 | + |
| 37 | +* Install the corresponding Magento 2 extensions from [Magento Marketplace](https://marketplace.magento.com/){:target:"_blank"} |
| 38 | + |
| 39 | + If the conflicting data originates from an extension which adds own database structure elements, then the Magento 2 version of the same extension may add such elements to the destination (Magento 2) database, thus fixing the issue. |
| 40 | + |
| 41 | +* Configure the Tool to ignore the problematic data |
| 42 | + |
| 43 | +To ignore database entities, add the `<ignore>` tag to an entity in the `map.xml` file, like this: |
| 44 | + |
| 45 | +{% highlight xml %} |
| 46 | +<ignore> |
| 47 | + <field>sales_order_address_id</field> |
| 48 | +</ignore> |
| 49 | +{% endhighlight %} |
| 50 | + |
| 51 | +<div class="bs-callout bs-callout-warning"> |
| 52 | + <p>Before ignoring entities, make sure you do not need the affected data in your Magento 2 store.</p> |
| 53 | +</div> |
| 54 | + |
| 55 | +### Class does not exist but mentioned |
| 56 | + |
| 57 | +{% highlight xml %} |
| 58 | +Class <extension/class_name> does not exist but mentioned in: |
| 59 | +<eav_attribute.frontend_model> for <attribute_id=196> |
| 60 | +{% endhighlight %} |
| 61 | + |
| 62 | +#### Explanation |
| 63 | + |
| 64 | +A class from Magento 1 codebase could not be found in Magento 2 codebase during the [EAV migration step]({{page.baseurl}}migration/migration-tool-internal-spec.html#eav). In most cases, the missing class belongs to an extension. |
| 65 | + |
| 66 | +#### Possible solutions |
| 67 | + |
| 68 | +* Install the corresponding Magento 2 extension |
| 69 | + |
| 70 | +* Ignore the attribute that causes the issue |
| 71 | + |
| 72 | + For this, add the attribute to the `ignore` group in the `eav-attribute-groups.xml.dist` file. |
| 73 | + |
| 74 | +* Add class mapping using the `class-map.xml.dist` file |
| 75 | + |
| 76 | +### Foreign key constraint fails |
| 77 | + |
| 78 | +#### Error message text |
| 79 | + |
| 80 | +{% highlight xml %} |
| 81 | +Foreign key <KEY_NAME> constraint fails. |
| 82 | +Orphan records id: <id_1>, <id_2> from <child_table>. |
| 83 | +<field_id> has no referenced records in <parent_table> |
| 84 | +{% endhighlight %} |
| 85 | + |
| 86 | +#### Explanation |
| 87 | + |
| 88 | +There are missing database records in the `parent_table` to which the `field_id` of the `child_table` is pointing to. |
| 89 | + |
| 90 | +#### Possible solution |
| 91 | + |
| 92 | +Delete the records from the `child_table`, if you do not need them. |
| 93 | + |
| 94 | +To keep the records, disable the `Data Integrity Step` by modifying the Data Migration Tool's `config.xml`. |
| 95 | + |
| 96 | +### Duplicates in URL rewrites |
| 97 | + |
| 98 | +{% highlight xml %} |
| 99 | +There are duplicates in URL rewrites: |
| 100 | +Request path: towel.html Store ID: 2 Target path: catalog/product/view/id/10 |
| 101 | +Request path: towel.html Store ID: 2 Target path: catalog/product/view/id/12 |
| 102 | +{% endhighlight %} |
| 103 | + |
| 104 | +#### Explanation |
| 105 | + |
| 106 | +The `Target path` in a URL rewrite must be specified by a unique pair of `Request path` + `Store ID`. This error reports two entries that use the same `Request path` + `Store ID` pair with two different `Target path` values. |
| 107 | + |
| 108 | +#### Possible solution |
| 109 | + |
| 110 | +Enable the `auto_resolve_urlrewrite_duplicates` option in your `config.xml` file. |
| 111 | + |
| 112 | +This configuration adds a hash-string to the conflicting records of URL reqwrites, and shows the resolution result in your command line interface. |
| 113 | + |
| 114 | +### Mismatch of entities |
| 115 | + |
| 116 | +{%highlight xml%} |
| 117 | +Mismatch of entities in the document: <DOCUMENT> |
| 118 | +{%endhighlight%} |
| 119 | + |
| 120 | +#### Explanation |
| 121 | + |
| 122 | +The error occurs during the Volume Check step. It means the Magento 2 database record count of the document is not the same as in Magento 1. |
| 123 | + |
| 124 | +Missing records happen when a customer places an order during migration. |
| 125 | + |
| 126 | +#### Solution |
| 127 | + |
| 128 | +Run the Data Migration Tool in `Delta` mode to transfer incremental changes. |
0 commit comments