framework,api,server,ui: improve error messaging by shwstppr · Pull Request #12336 · apache/cloudstack

shwstppr · 2025-12-24T10:40:47Z

Description

Framework level improvements for for contextual and localized API error messages

Design spec: Error Message Consistency, Customization, and Localization Framework

Types of changes

Breaking change (fix or feature that would cause existing functionality to change)
New feature (non-breaking change which adds functionality)
Bug fix (non-breaking change which fixes an issue)
Enhancement (improves an existing feature and functionality)
Cleanup (Code refactoring and cleanup, that may add test cases)
Build/CI
Test (unit or integration test code)

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Major
Minor

Bug Severity

Screenshots (if appropriate):

Refined error message with additional context for admin

User facing error, with localization

Example API response

{
    "deployvirtualmachineresponse": {
        "uuidList": [],
        "errorcode": 535,
        "cserrorcode": 9999,
        "errortext": "Unable to deploy Instance because allocating 1 more Instance would exceed the Account limits. Current: 2, Reserved: 0, Limit: 2. Release unused resources, then retry.",
        "errortextkey": "vm.deploy.resourcelimit.exceeded.account",
        "errormetadata": {
            "resourceRequested": "1",
            "resourceTypeDisplay": "Instance",
            "resourceOwnerType": "Account",
            "resourceAmount": "2",
            "resourceReserved": "0",
            "resourceLimit": "2"
        }
    }
}

How Has This Been Tested?

How did you try to break this feature and the system with this change?

codecov · 2025-12-24T10:49:06Z

Codecov Report

❌ Patch coverage is 42.81609% with 398 lines in your changes missing coverage. Please review.
✅ Project coverage is 18.96%. Comparing base (d2c8aa7) to head (b2f8ba9).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
.../apache/cloudstack/vm/UnmanagedVMsManagerImpl.java	16.55%	126 Missing ⚠️
...n/java/com/cloud/vm/VirtualMachineManagerImpl.java	13.67%	101 Missing ⚠️
...he/cloudstack/context/ResponseMessageResolver.java	80.09%	26 Missing and 17 partials ⚠️
...n/java/org/apache/cloudstack/error/Exceptions.java	39.34%	36 Missing and 1 partial ⚠️
...ava/org/apache/cloudstack/context/CallContext.java	27.58%	18 Missing and 3 partials ⚠️
.../cloud/resourcelimit/ResourceLimitManagerImpl.java	0.00%	20 Missing ⚠️
...he/cloudstack/api/command/user/vm/DeployVMCmd.java	0.00%	9 Missing ⚠️
...c/main/java/com/cloud/user/AccountManagerImpl.java	50.00%	4 Missing and 3 partials ⚠️
...m/cloud/utils/exception/CloudRuntimeException.java	66.66%	6 Missing ⚠️
...main/java/com/cloud/api/ApiAsyncJobDispatcher.java	0.00%	5 Missing ⚠️
... and 10 more

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #12336      +/-   ##
============================================
+ Coverage     18.93%   18.96%   +0.03%     
- Complexity    18471    18533      +62     
============================================
  Files          6221     6223       +2     
  Lines        560045   560464     +419     
  Branches      68289    68339      +50     
============================================
+ Hits         106048   106296     +248     
- Misses       442372   442517     +145     
- Partials      11625    11651      +26

Flag	Coverage Δ
uitests	`3.50% <ø> (+<0.01%)`	⬆️
unittests	`20.17% <42.81%> (+0.03%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-01-26T07:21:01Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

github-actions · 2026-01-28T14:25:32Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

shwstppr · 2026-02-09T05:05:21Z

@blueorangutan package

blueorangutan · 2026-02-09T05:06:04Z

@shwstppr a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-02-09T06:01:57Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 16743

github-actions · 2026-03-26T16:36:17Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

github-actions · 2026-06-30T04:52:52Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

Signed-off-by: Abhishek Kumar <abhishek.mrt22@gmail.com>

shwstppr · 2026-07-01T06:25:17Z

@blueorangutan package

blueorangutan · 2026-07-01T06:26:05Z

@shwstppr a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-07-01T07:20:00Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 18426

Signed-off-by: Abhishek Kumar <abhishek.mrt22@gmail.com>

Copilot

Pull request overview

This PR introduces a framework for contextual, consistent, and localizable API error messages across CloudStack server-side exceptions and the UI, backed by a centralized error-messages.json template file and metadata propagation.

Changes:

Add an error-message resolution pipeline (ResponseMessageResolver, Exceptions helpers) and extend API exception responses with errortextkey + errormetadata.
Propagate richer error context (notably resource-limit details) via CallContext so errors can be templated/expanded consistently.
Update UI notifications to prefer localized templates when errortextkey/errormetadata are present; add packaging + tooling support for the new error-messages file.

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
utils/src/main/java/com/cloud/utils/StringUtils.java	Adds a small null-safe string helper.
utils/src/main/java/com/cloud/utils/exception/CloudRuntimeException.java	Adds message-key and metadata fields to runtime exceptions.
ui/src/utils/plugins.js	Adds localization-aware error notification handling and a locale error utility plugin.
ui/src/main.js	Registers the new UI locale error plugin.
test/integration/smoke/test_vm_strict_host_tags.py	Updates assertions to new “Instance” wording (contains a syntax issue).
test/integration/smoke/test_deploy_vm_root_resize.py	Updates expected error text for root disk size validations (contains logic/scope issues).
server/src/test/java/org/apache/cloudstack/vm/UnmanagedVMsManagerImplTest.java	Adjusts mocks for UUID usage in new error handling paths.
server/src/test/java/org/apache/cloudstack/storage/sharedfs/SharedFSServiceImplTest.java	Updates `isRootAdmin` mocking signature expectations.
server/src/test/java/com/cloud/vm/UserVmManagerImplTest.java	Migrates assertions toward messageKey usage (one assertion still checks `getMessage()`).
server/src/test/java/com/cloud/storage/StorageManagerImplTest.java	Refactors imports + updates admin-check mocking signature.
server/src/test/java/com/cloud/storage/snapshot/SnapshotManagerImplTest.java	Refactors imports + updates admin-check mocking signature.
server/src/main/java/com/cloud/user/AccountManagerImpl.java	Adds `isRootAdmin(Account)` overload and reuses it from `isRootAdmin(Long)`.
server/src/main/java/com/cloud/resourcelimit/ResourceLimitManagerImpl.java	Populates `CallContext` error-context metadata for resource-limit errors.
server/src/main/java/com/cloud/api/ResponseObjectTypeAdapter.java	Serializes `ExceptionResponse` via Gson helper and strips `uuidList`.
server/src/main/java/com/cloud/api/ApiServer.java	Injects `ResponseMessageResolver` into API error serialization path.
server/src/main/java/com/cloud/api/ApiAsyncJobDispatcher.java	Ensures async-job error responses are enriched with messageKey/metadata when available.
scripts/util/error_messages_tool.py	Adds a utility to audit/fix/sort/find-unused keys in the error-messages JSON.
pom.xml	Excludes the generated/managed error-messages file from checks (e.g., RAT).
plugins/network-elements/juniper-contrail/src/test/java/org/apache/cloudstack/network/contrail/management/MockAccountManager.java	Adds stub for new `isRootAdmin(Account)` API in test mock.
packaging/el8/cloud.spec	Installs `error-messages.json` into management config packaging.
framework/jobs/src/main/java/org/apache/cloudstack/framework/jobs/impl/JobSerializerHelper.java	Normalizes CloudRuntimeException metadata before job serialization.
engine/schema/src/main/java/org/apache/cloudstack/engine/cloud/entity/api/db/VMEntityVO.java	Renames `displayname` field/accessors to `displayName`.
engine/schema/src/main/java/com/cloud/user/UserVO.java	Minor `toString()` formatting change + import order.
engine/schema/src/main/java/com/cloud/user/UserAccountVO.java	Minor `toString()` formatting change.
engine/schema/src/main/java/com/cloud/service/ServiceOfferingVO.java	Minor `toString()` formatting change.
engine/orchestration/src/test/java/com/cloud/vm/VirtualMachineManagerImplTest.java	Updates tests to assert messageKey-based errors.
engine/orchestration/src/main/java/org/apache/cloudstack/engine/cloud/entity/api/VirtualMachineEntityImpl.java	Aligns to new `VMEntityVO.setDisplayName()` method.
engine/orchestration/src/main/java/com/cloud/vm/VirtualMachineManagerImpl.java	Converts many runtime/parameter exceptions to key+metadata-based exceptions via `Exceptions.*`.
debian/cloudstack-management.install	Installs `error-messages.json` in Debian packaging.
client/conf/error-messages.json.in	Adds the initial error message template catalog (contains template/typo issues).
api/src/test/java/org/apache/cloudstack/context/ResponseMessageResolverTest.java	Adds unit tests for resolver expansion/metadata handling.
api/src/main/java/org/apache/cloudstack/error/Exceptions.java	Adds helpers to construct exceptions with resolved messageKey/metadata.
api/src/main/java/org/apache/cloudstack/context/ResponseMessageResolver.java	Adds template loading, metadata merging, and message expansion logic.
api/src/main/java/org/apache/cloudstack/context/CallContext.java	Adds error-context storage + root-admin detection helper.
api/src/main/java/org/apache/cloudstack/api/response/ExceptionResponse.java	Extends API error response with `errortextkey` and `errormetadata`.
api/src/main/java/org/apache/cloudstack/api/command/user/vm/DeployVMCmd.java	Maps resource-limit allocation exceptions to stable error keys.
api/src/main/java/org/apache/cloudstack/api/command/user/vm/BaseDeployVMCmd.java	Converts numeric parsing failure to key+metadata InvalidParameterValueException.
api/src/main/java/com/cloud/user/AccountService.java	Adds `isRootAdmin(Account)` to the public account service interface.
api/src/main/java/com/cloud/configuration/Resource.java	Adds a display name to `ResourceType` for better user-facing messaging.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+        except Exception as e
+            self.assertTrue("Unable to orchestrate the start of Instance" in str(e))


                )
            except Exception as ex:
-                    if "rootdisksize override (" + str(newrootsize) + " GB) is smaller than template size" in str(ex):
-                        success = True
-                    else:
-                        self.debug("Virtual machine create did not fail appropriately. Error was actually : " + str(ex));
+                success = True
+            else:
+                self.debug("Virtual machine create did not fail appropriately. Error was actually : " + str(ex))


            userVmManagerImpl.unmanageUserVM(vmId, null);
        });
-        assertEquals("Instance: test-vm is not running or stopped, cannot be unmanaged", exception.getMessage());
+        assertEquals("vm.unmanage.vm.not.right.state", exception.getMessage());
        verify(userVmDao, times(1)).releaseFromLockTable(vmId);


+      if (params && params.constructor === Object) {
+        for (const paramKey in params) {
+          localeMsg = localeMsg.replace(`{{${paramKey}}}`, params[paramKey])
+        }
+      }


+    "vm.updatenic.work.nic.not.found": "Unable to update NIC as the specified NIC is not found.",
+    "vm.updatenic.work.nic.not.found.admin": "Unable to update NIC as the specified NIC ID: {{nicId} is not found.",
+    "vm.updatenic.zone.basic.not.allowed": "Zone {{zone}}, has a NetworkType of Basic. Can't change default NIC on a Basic Network.",


+    "vm.scale.reconfigure.answer.failed": "Unable to scale Instance: {{error}}.",
+    "vm.scale.root.volume.change.failed": "Failed to change disk offering of the root volume.",
+    "vm.scale.source.host.not.found": "Unable to find source host for Instance scaling migration.",
+    "vm.scale.up.required": "While the VM is running, only scalling up it is supported. New service offering {{newOffering}} should have at least one value (ram, speed or cpu) greater than the current values {{currentOffering}}.",


+    "vm.upgrade.storage.shared.to.local": "Unable to upgrade Instance {{instance}}: target service offering uses shared storage but the volume is in a local storage pool.",
+    "vm.upgrade.system.use.mismatch": "Unable to upgrade Instance: the system use property differs between the current and new service offering.",
+    "vm.upgrade.vm.not.right.state": "Unable to upgrade Instance {{instance}} in state {{instanceState}}; make sure the Instance is stopped.",
+    "vm.upgrade.vm.sunning.scale.down.unsupported": "Scaling down is not supported while the VM is running. The new service offering attributes {\"memory\": {{newMemory}}, \"CPU speed\": {{newSpeed}}, \"vCPUs\": {{newCPU}}} must not be lower than the current values {\"memory\": {{currentMemory}}, \"CPU speed\": {{currentSpeed}}, \"vCPUs\": {{currentCPU}}}.",


boring-cyborg Bot added component:api component:networking component:packaging component:UI distro:ubuntu labels Dec 24, 2025

shwstppr force-pushed the improve-error-messages branch from 86379b7 to c938bd1 Compare December 24, 2025 11:55

boring-cyborg Bot added the component:build label Dec 24, 2025

shwstppr closed this Jan 6, 2026

shwstppr reopened this Jan 6, 2026

apache deleted a comment from blueorangutan Jan 6, 2026

github-actions Bot added the status:has-conflicts label Jan 26, 2026

github-actions Bot removed the status:has-conflicts label Jan 27, 2026

DaanHoogland added this to the 4.22.1 milestone Jan 28, 2026

github-actions Bot added the status:has-conflicts label Jan 28, 2026

github-actions Bot removed the status:has-conflicts label Jan 29, 2026

sureshanaparti added this to Apache CloudStack 4.22.1 Feb 3, 2026

sureshanaparti moved this to In Progress in Apache CloudStack 4.22.1 Feb 3, 2026

apache deleted a comment from blueorangutan Feb 9, 2026

github-actions Bot added the status:has-conflicts label Mar 26, 2026

boring-cyborg Bot added component:simulator component:solidfire component:storage component:vmware component:vpc component:vxlan VXLAN component:XenServer Python Warning... Python code Ahead! docker labels Jun 29, 2026

shwstppr removed component:kvm component:management-server component:XenServer component:vmware component:primary-storage component:secondary-storage component:vpc component:mysql component:security-group component:networking labels Jun 29, 2026

shwstppr added 5 commits June 30, 2026 13:50

fix

97a4629

Signed-off-by: Abhishek Kumar <abhishek.mrt22@gmail.com>

Merge remote-tracking branch 'apache/main' into improve-error-messages

1c16372

changes

c2dc7f1

Signed-off-by: Abhishek Kumar <abhishek.mrt22@gmail.com>

error msg tool

153bfe4

Signed-off-by: Abhishek Kumar <abhishek.mrt22@gmail.com>

build fix

02b5fd8

Signed-off-by: Abhishek Kumar <abhishek.mrt22@gmail.com>

fixes

b2f8ba9

Signed-off-by: Abhishek Kumar <abhishek.mrt22@gmail.com>

Copilot AI reviewed Jul 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

framework,api,server,ui: improve error messaging#12336

framework,api,server,ui: improve error messaging#12336
shwstppr wants to merge 30 commits into
apache:mainfrom
shapeblue:improve-error-messages

shwstppr commented Dec 24, 2025 •

edited

Loading

Uh oh!

codecov Bot commented Dec 24, 2025 •

edited

Loading

Uh oh!

github-actions Bot commented Jan 26, 2026

Uh oh!

github-actions Bot commented Jan 28, 2026

Uh oh!

shwstppr commented Feb 9, 2026

Uh oh!

blueorangutan commented Feb 9, 2026

Uh oh!

blueorangutan commented Feb 9, 2026

Uh oh!

github-actions Bot commented Mar 26, 2026

Uh oh!

github-actions Bot commented Jun 30, 2026

Uh oh!

shwstppr commented Jul 1, 2026

Uh oh!

blueorangutan commented Jul 1, 2026

Uh oh!

blueorangutan commented Jul 1, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		except Exception as e
		self.assertTrue("Unable to orchestrate the start of Instance" in str(e))

Uh oh!

Conversation

shwstppr commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Types of changes

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Bug Severity

Screenshots (if appropriate):

Example API response

How Has This Been Tested?

How did you try to break this feature and the system with this change?

Uh oh!

codecov Bot commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jan 26, 2026

Uh oh!

github-actions Bot commented Jan 28, 2026

Uh oh!

shwstppr commented Feb 9, 2026

Uh oh!

blueorangutan commented Feb 9, 2026

Uh oh!

blueorangutan commented Feb 9, 2026

Uh oh!

github-actions Bot commented Mar 26, 2026

Uh oh!

github-actions Bot commented Jun 30, 2026

Uh oh!

shwstppr commented Jul 1, 2026

Uh oh!

blueorangutan commented Jul 1, 2026

Uh oh!

blueorangutan commented Jul 1, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

shwstppr commented Dec 24, 2025 •

edited

Loading

codecov Bot commented Dec 24, 2025 •

edited

Loading