conditional error reporting for vm move failure

api/src/main/java/com/cloud/vm/UserVmService.java

@@ -40,6 +40,7 @@ import org.apache.cloudstack.api.command.user.vm.UpdateVmNicIpCmd;
 import org.apache.cloudstack.api.command.user.vm.UpgradeVMCmd;
 import org.apache.cloudstack.api.command.user.vmgroup.CreateVMGroupCmd;
 import org.apache.cloudstack.api.command.user.vmgroup.DeleteVMGroupCmd;
+import org.apache.cloudstack.framework.config.ConfigKey;
 
 import com.cloud.dc.DataCenter;
 import com.cloud.deploy.DeploymentPlanner;
@@ -64,6 +65,11 @@ import com.cloud.utils.exception.ExecutionException;
 
 public interface UserVmService {
 
+    ConfigKey<Boolean> AllowExposingVmAssignFailureDetails = new ConfigKey<>("Advanced", Boolean.class,
+            "vm.assign.failure.detailed.message.enabled", "true",
+            "If true, the reason a VM ownership change (assignVirtualMachine) fails, e.g. remaining port forwarding rules or volume snapshots, is returned to the API caller. " +
+            "If false, only a generic error message referencing the Instance ID is returned, and the detailed reason is only available in the management server logs.",
+            true, ConfigKey.Scope.Global);
 
     /**
      * Destroys one virtual machine

api/src/main/java/org/apache/cloudstack/api/command/admin/vm/AssignVMCmd.java

@@ -36,6 +36,7 @@ import org.apache.cloudstack.api.response.UserVmResponse;
 import com.cloud.exception.InvalidParameterValueException;
 import com.cloud.user.Account;
 import com.cloud.uservm.UserVm;
+import com.cloud.vm.UserVmService;
 import com.cloud.vm.VirtualMachine;
 
 @APICommand(name = "assignVirtualMachine",
@@ -128,6 +129,9 @@ public class AssignVMCmd extends BaseCmd  {
             ApiErrorCode errorCode = e instanceof InvalidParameterValueException ? ApiErrorCode.PARAM_ERROR : ApiErrorCode.INTERNAL_ERROR;
             String msg = String.format("Failed to move Instance due to [%s].", getVmId());
             logger.error(msg, e);
+            if (e instanceof InvalidParameterValueException && UserVmService.AllowExposingVmAssignFailureDetails.value()) {
+                msg = e.getMessage();
+            }
             throw new ServerApiException(errorCode, msg);
         }
     }

server/src/main/java/com/cloud/vm/UserVmManagerImpl.java

@@ -8891,7 +8891,7 @@ public class UserVmManagerImpl extends ManagerBase implements UserVmManager, Vir
         return new ConfigKey<?>[] {EnableDynamicallyScaleVm, AllowDiskOfferingChangeDuringScaleVm, AllowUserExpungeRecoverVm, VmIpFetchWaitInterval, VmIpFetchTrialMax,
                 VmIpFetchThreadPoolMax, VmIpFetchTaskWorkers, AllowDeployVmIfGivenHostFails, EnableAdditionalVmConfig, DisplayVMOVFProperties,
                 KvmAdditionalConfigAllowList, XenServerAdditionalConfigAllowList, VmwareAdditionalConfigAllowList, DestroyRootVolumeOnVmDestruction,
-                EnforceStrictResourceLimitHostTagCheck, StrictHostTags, AllowUserForceStopVm};
+                EnforceStrictResourceLimitHostTagCheck, StrictHostTags, AllowUserForceStopVm, AllowExposingVmAssignFailureDetails};
     }
 
     @Override