From 3ba2897597eb6a54733bf9394f2c63c1fb60cd85 Mon Sep 17 00:00:00 2001 From: Marks Troicins Date: Wed, 14 Oct 2026 10:40:23 +0200 Subject: [PATCH 1/3] [SOLP-4253] Document mx.exe module-import update changes --- .../general/mx-command-line-tool/module.md | 54 +++++++++++-------- 1 file changed, 33 insertions(+), 21 deletions(-) diff --git a/content/en/docs/refguide/general/mx-command-line-tool/module.md b/content/en/docs/refguide/general/mx-command-line-tool/module.md index 07dfd5433f2..3e952b24f64 100644 --- a/content/en/docs/refguide/general/mx-command-line-tool/module.md +++ b/content/en/docs/refguide/general/mx-command-line-tool/module.md @@ -87,41 +87,44 @@ This table shows the return codes and their description: ## mx module-import Command {#module-import} -The `mx module-import` command imports a source module (*.mpk*) into an app. +The `mx module-import` command imports a source module (*.mpk*) into an app, or updates a module that already exists in the app. + +{{% alert color="info" %}} +As of Studio Pro 11.16, the `update` import mode performs a three-way merge and restores storage GUIDs, in the same way as the **Update from file** option in Studio Pro. The `replace` import mode, and with it the `--metadata` option, is no longer available. +{{% /alert %}} {{% alert color="warning" %}} -In Studio Pro 11.14, the `mx.exe module-import replace` and `mx.exe module-import update` commands will not rescue storage GUIDs after a module update, which will result in data loss. +In Studio Pro 11.14 and 11.15, the `mx.exe module-import replace` and `mx.exe module-import update` commands will not rescue storage GUIDs after a module update, which will result in data loss. {{% /alert %}} ### Usage Use the following command pattern for `mx module-import`: -`mx module-import MPK_PATH MPR_PATH [--import-mode ] [--conflict ] [--metadata ]` +`mx module-import MPK_PATH MPR_PATH [--import-mode ] [--original-mpk ] [--module-name ] [--conflict ]` -For `MPK_PATH`, enter a *.mpk* file with the module you want to import. +For `MPK_PATH`, enter a *.mpk* file with the module you want to import. When updating a module, this is the new version of the module. For `MPR_PATH`, enter a *.mpr* file of the project you want to import a module into. -For `--import-mode`, enter one of the following values to control what happens when a module with the same name already exists in the app: +For `--import-mode`, enter one of the following values: * `add` – Add the module. Fails if a module with the same name already exists. This is the default. -* `replace` – Replace the existing module. Fails with exit code `310` if no module with that name is found in the app. -* `update` – Replace the module if it already exists, or add it if it does not. +* `update` – Update a module that already exists in the app by performing a three-way merge between the original module package, your app's version of the module, and the new module package. Storage GUIDs are restored, so no data is lost. Fails with exit code `314` if the module is not found in the app. -For `--conflict`, enter one of the following values to control what happens when a same-name module already exists. This applies to the `add` and `update` modes: +For `--original-mpk`, enter the *.mpk* file of the module version that is currently installed in the app. This is used as the common base for the three-way merge. This option is required when `--import-mode update` is used. -* `fail` – Return an error. This is the default. -* `take_mine` – Keep the existing module and skip the import silently. -* `take_theirs` – Replace the existing module. +For `--module-name`, enter the name of the module in the app that you want to update. This option only applies to `--import-mode update`. Use it when the module in your app has a different name than the module in the *.mpk* file, for example, when the same module was imported more than once under different names. If this option is not specified, the name of the module in the *.mpk* file is used. -For `--metadata`, enter one of the following values to control how Marketplace identity fields are handled when a module is replaced. This option only takes effect when a replacement actually occurs: +For `--conflict`, enter one of the following values to control what happens when the three-way merge results in conflicts. This applies to the `update` mode: -* `take_new` – Use the identity fields from the incoming module. This is the default. -* `take_existing` – Copy the identity fields from the module being replaced. -* `erase` – Clear all identity fields. +* `fail` – Return an error with exit code `313` and revert the app to its state before the update. This is the default. +* `take_mine` – Resolve all conflicts by keeping the version in your app. +* `take_theirs` – Resolve all conflicts by using the version from the new module package. -Regardless of the chosen strategy, `FromAppStore` is always inherited from the existing module, and `AppStoreVersion` falls back to the existing values when the incoming module does not provide them. +{{% alert color="info" %}} +The app is only reverted automatically when it is under Git version control. Make sure there are no uncommitted changes before you update a module. If the app is not under version control, you need to restore it manually after a failed update. +{{% /alert %}} ### Examples @@ -129,13 +132,17 @@ Add a module to an app: `mx module-import MyNewModule.mpk MyApp.mpr` -Replace an existing module, keeping its marketplace identity: +Update an existing module from version 1.0.0 to version 2.0.0: + +`mx module-import MyModule_2.0.0.mpk MyApp.mpr --import-mode update --original-mpk MyModule_1.0.0.mpk` + +Update an existing module and resolve any conflicts by using the new version: -`mx module-import MyNewModule.mpk MyApp.mpr --import-mode replace --metadata take_existing` +`mx module-import MyModule_2.0.0.mpk MyApp.mpr --import-mode update --original-mpk MyModule_1.0.0.mpk --conflict take_theirs` -Update a module if it exists or add it if not, overwriting on collision: +Update a module that has a different name in the app than in the module package: -`mx module-import MyNewModule.mpk MyApp.mpr --import-mode update --conflict take_theirs` +`mx module-import MyModule_2.0.0.mpk MyApp.mpr --import-mode update --original-mpk MyModule_1.0.0.mpk --module-name MyRenamedModule` ### Return Codes @@ -162,8 +169,13 @@ In case of errors, the exit code consists of three digits `XYZ`: * 7 – Module can't be loaded * 8 – Import of a module failed. Resulting project can't be saved. * 9 – File does not exist - * 10 – `--import-mode replace` was specified but no module with that name exists in the project + * 10 – `--import-mode replace` was specified but no module with that name exists in the project (Studio Pro 11.14 and 11.15 only) * 11 – The *.mpk* file has an unrecognized extension + * 12 – `--original-mpk` was not provided for `--import-mode update` + * 13 – The three-way merge resulted in unresolved conflicts and the project has been reverted. Retry with `--conflict take_mine` or `--conflict take_theirs` to resolve the conflicts automatically. + * 14 – `--import-mode update` was specified but no module with that name exists in the project + * 15 – A previous module update was interrupted. Revert the project and delete the `.mendix-cache/updates/` directory before retrying. + * 16 – A module update is already in progress. Commit or revert the pending changes and delete the `.mendix-cache/updates/` directory before retrying. For example: From 9b7ba4481be909399187aa43bef4fbef6413e218 Mon Sep 17 00:00:00 2001 From: Quinn Tracy <142489060+quinntracy@users.noreply.github.com> Date: Tue, 20 Oct 2026 10:37:56 +0200 Subject: [PATCH 2/3] Review --- .../general/mx-command-line-tool/module.md | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/content/en/docs/refguide/general/mx-command-line-tool/module.md b/content/en/docs/refguide/general/mx-command-line-tool/module.md index 3e952b24f64..864c0526a11 100644 --- a/content/en/docs/refguide/general/mx-command-line-tool/module.md +++ b/content/en/docs/refguide/general/mx-command-line-tool/module.md @@ -87,10 +87,10 @@ This table shows the return codes and their description: ## mx module-import Command {#module-import} -The `mx module-import` command imports a source module (*.mpk*) into an app, or updates a module that already exists in the app. +The `mx module-import` command imports a source module (*.mpk*) into an app, or updates a module that already exists. {{% alert color="info" %}} -As of Studio Pro 11.16, the `update` import mode performs a three-way merge and restores storage GUIDs, in the same way as the **Update from file** option in Studio Pro. The `replace` import mode, and with it the `--metadata` option, is no longer available. +As of Studio Pro 11.16, the `update` import mode performs a three-way merge and restores storage GUIDs, in the same way as the **Update from file** option in Studio Pro. The `replace` import mode and the `--metadata` option is no longer available. {{% /alert %}} {{% alert color="warning" %}} @@ -128,21 +128,21 @@ The app is only reverted automatically when it is under Git version control. Mak ### Examples -Add a module to an app: +* Add a module to an app: -`mx module-import MyNewModule.mpk MyApp.mpr` + `mx module-import MyNewModule.mpk MyApp.mpr` -Update an existing module from version 1.0.0 to version 2.0.0: +* Update an existing module from version 1.0.0 to version 2.0.0: -`mx module-import MyModule_2.0.0.mpk MyApp.mpr --import-mode update --original-mpk MyModule_1.0.0.mpk` + `mx module-import MyModule_2.0.0.mpk MyApp.mpr --import-mode update --original-mpk MyModule_1.0.0.mpk` -Update an existing module and resolve any conflicts by using the new version: +* Update an existing module and resolve any conflicts by using the new version: -`mx module-import MyModule_2.0.0.mpk MyApp.mpr --import-mode update --original-mpk MyModule_1.0.0.mpk --conflict take_theirs` + `mx module-import MyModule_2.0.0.mpk MyApp.mpr --import-mode update --original-mpk MyModule_1.0.0.mpk --conflict take_theirs` -Update a module that has a different name in the app than in the module package: +* Update a module that has a different name in the app than in the module package: -`mx module-import MyModule_2.0.0.mpk MyApp.mpr --import-mode update --original-mpk MyModule_1.0.0.mpk --module-name MyRenamedModule` + `mx module-import MyModule_2.0.0.mpk MyApp.mpr --import-mode update --original-mpk MyModule_1.0.0.mpk --module-name MyRenamedModule` ### Return Codes @@ -152,9 +152,9 @@ In case of errors, the exit code consists of three digits `XYZ`: * X determines the error type: - * 1 – parameter validation error - * 2 – output-related error - * 3 – errors related to the execution of the operation + * 1 – Parameter validation error + * 2 – Output-related error + * 3 – Errors related to the execution of the operation * Y is the number of the parameter the error is related to. This component is only valid if X = 1. If the error is not related to the parameters, Y contains the error details code described in Z below. @@ -164,16 +164,16 @@ In case of errors, the exit code consists of three digits `XYZ`: * 2 – Module you are trying to import is a Theme module and cannot be imported. * 3 – Project already contains a module with the same name as the module you are importing. Thus the module cannot be imported. * 4 – No module is found in the MPK package. - * 5 – Project Version is not supported by the current version of mx.exe - * 6 – Project can't be loaded - * 7 – Module can't be loaded + * 5 – Project Version is not supported by the current version of mx.exe. + * 6 – Project can't be loaded. + * 7 – Module can't be loaded. * 8 – Import of a module failed. Resulting project can't be saved. - * 9 – File does not exist - * 10 – `--import-mode replace` was specified but no module with that name exists in the project (Studio Pro 11.14 and 11.15 only) - * 11 – The *.mpk* file has an unrecognized extension - * 12 – `--original-mpk` was not provided for `--import-mode update` + * 9 – File does not exist. + * 10 – `--import-mode replace` was specified but no module with that name exists in the project (Studio Pro 11.14 and 11.15 only). + * 11 – The *.mpk* file has an unrecognized extension. + * 12 – `--original-mpk` was not provided for `--import-mode update`. * 13 – The three-way merge resulted in unresolved conflicts and the project has been reverted. Retry with `--conflict take_mine` or `--conflict take_theirs` to resolve the conflicts automatically. - * 14 – `--import-mode update` was specified but no module with that name exists in the project + * 14 – `--import-mode update` was specified but no module with that name exists in the project. * 15 – A previous module update was interrupted. Revert the project and delete the `.mendix-cache/updates/` directory before retrying. * 16 – A module update is already in progress. Commit or revert the pending changes and delete the `.mendix-cache/updates/` directory before retrying. From f35b287e2422b272fe1441ce32e0750150d00fb8 Mon Sep 17 00:00:00 2001 From: Marks Troicins Date: Tue, 27 Oct 2026 12:35:12 +0100 Subject: [PATCH 3/3] [SOLP-4253] Add known issue for mismatched package IDs --- .../en/docs/refguide/general/mx-command-line-tool/module.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/en/docs/refguide/general/mx-command-line-tool/module.md b/content/en/docs/refguide/general/mx-command-line-tool/module.md index 864c0526a11..2353a3f89de 100644 --- a/content/en/docs/refguide/general/mx-command-line-tool/module.md +++ b/content/en/docs/refguide/general/mx-command-line-tool/module.md @@ -122,6 +122,10 @@ For `--conflict`, enter one of the following values to control what happens when * `take_mine` – Resolve all conflicts by keeping the version in your app. * `take_theirs` – Resolve all conflicts by using the version from the new module package. +{{% alert color="warning" %}} +Updating a module from the command line is not supported if the package IDs of the original module package, the new module package, and the module in your app do not match. +{{% /alert %}} + {{% alert color="info" %}} The app is only reverted automatically when it is under Git version control. Make sure there are no uncommitted changes before you update a module. If the app is not under version control, you need to restore it manually after a failed update. {{% /alert %}}