framework,api,server,ui: improve error messaging - #12336
Conversation
Sorry, something went wrong.
Codecov Report❌ Patch coverage is 42.81609% with 398 lines in your changes missing coverage. Please review. @@ Coverage Diff @@
## main #12336 +/- ##
============================================
- Coverage 20.40% 19.19% -1.22%
- Complexity 18787 18841 +54
============================================
Files 5757 6238 +481
Lines 520921 562474 +41553
Branches 60823 68669 +7846
============================================
+ Hits 106282 107952 +1670
- Misses 403062 442726 +39664
- Partials 11577 11796 +219
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness.
|
Sorry, something went wrong.
|
This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch. |
Sorry, something went wrong.
|
This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch. |
Sorry, something went wrong.
|
@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. |
Sorry, something went wrong.
|
Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 16743 |
Sorry, something went wrong.
|
This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch. |
Sorry, something went wrong.
|
This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch. |
Sorry, something went wrong.
Signed-off-by: Abhishek Kumar <abhishek.mrt22@gmail.com>
|
@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. |
Sorry, something went wrong.
|
Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 18426 |
Sorry, something went wrong.
There was a problem hiding this comment.
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.
Sorry, something went wrong.
| 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)) |
|
This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch. |
Sorry, something went wrong.
Signed-off-by: Abhishek Kumar <abhishek.mrt22@gmail.com>
|
This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch. |
Sorry, something went wrong.
Description
Framework level improvements for for contextual and localized API error messages
Design spec: Error Message Consistency, Customization, and Localization Framework
Types of changes
Feature/Enhancement Scale or Bug Severity
Feature/Enhancement Scale
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?