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 contextual and localized API error messages

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

Documentation PR: apache/cloudstack-documentation#684

Developed focused documentation is also added at api/src/main/java/org/apache/cloudstack/error/README.md

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?

End-to-end testing and the following smoke test,

[root@qa1-improve-err-88bf966b-kvm-mgmt1 marvin]# nosetests --with-xunit --xunit-file=results.xml --with-marvin --marvin-config=./marvin.cfg -s -a tags=advanced --hypervisor=KVM tests/smoke/test_error_message_framework.py 
/usr/local/lib/python3.6/site-packages/paramiko/transport.py:32: CryptographyDeprecationWarning: Python 3.6 is no longer supported by the Python core team. Therefore, support for it is deprecated in cryptography. The next release of cryptography will remove support for Python 3.6.
  from cryptography.hazmat.backends import default_backend

==== Marvin Init Started ====

=== Marvin Parse Config Successful ===

=== Marvin Setting TestData Successful===

==== Log Folder Path: /tmp/MarvinLogs/Sep_18_2026_04_59_46_OYCP7L All logs will be available here ====

=== Marvin Init Logging Successful===

==== Marvin Init Successful ====
=== TestName: test_01_runtime_error_message_override_for_regular_user | Status : SUCCESS ===

=== TestName: test_02_runtime_error_message_override_for_admin | Status : SUCCESS ===

=== Final results are now copied to: /tmp//MarvinLogs/test_error_message_framework_DBR9CT ===

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 64.72492% with 218 lines in your changes missing coverage. Please review.
✅ Project coverage is 18.08%. Comparing base (2e63c60) to head (f6fc9ad).
⚠️ Report is 6 commits behind head on 4.22.

Files with missing lines	Patch %	Lines
...n/java/com/cloud/vm/VirtualMachineManagerImpl.java	11.72%	128 Missing ⚠️
...n/java/org/apache/cloudstack/error/Exceptions.java	50.68%	34 Missing and 2 partials ⚠️
...he/cloudstack/context/ResponseMessageResolver.java	86.58%	17 Missing and 16 partials ⚠️
...udstack/engine/cloud/entity/api/db/VMEntityVO.java	0.00%	4 Missing ⚠️
...rc/main/java/com/cloud/configuration/Resource.java	90.90%	2 Missing ⚠️
...loudstack/api/command/user/vm/BaseDeployVMCmd.java	0.00%	2 Missing ⚠️
...ava/org/apache/cloudstack/context/CallContext.java	93.10%	0 Missing and 2 partials ⚠️
...ine/cloud/entity/api/VirtualMachineEntityImpl.java	0.00%	2 Missing ⚠️
...main/java/com/cloud/api/ApiAsyncJobDispatcher.java	60.00%	2 Missing ⚠️
...c/main/java/com/cloud/user/AccountManagerImpl.java	85.71%	1 Missing and 1 partial ⚠️
... and 5 more

Additional details and impacted files

@@             Coverage Diff              @@
##               4.22   #12336      +/-   ##
============================================
+ Coverage     18.00%   18.08%   +0.07%     
- Complexity    16219    16336     +117     
============================================
  Files          5936     5938       +2     
  Lines        535716   536130     +414     
  Branches      65596    65650      +54     
============================================
+ Hits          96459    96960     +501     
+ Misses       428268   428138     -130     
- Partials      10989    11032      +43

Flag	Coverage Δ
uitests	`4.03% <ø> (+<0.01%)`	⬆️
unittests	`19.16% <64.72%> (+0.08%)`	⬆️

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.

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.

Framework-level improvements for for contextual and localized API error messages Design doc: https://cwiki.apache.org/confluence/display/CLOUDSTACK/Error+Message+Consistency%2C+Customization%2C+and+Localization+Framework Signed-off-by: Abhishek Kumar <[email protected]>

shwstppr · 2026-09-03T08:59:30Z

@blueorangutan package

blueorangutan · 2026-09-03T09:00:06Z

@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-09-03T10:00:59Z

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

github-actions · 2026-09-10T11:46:05Z

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 <[email protected]>

shwstppr · 2026-09-18T07:47:03Z

@blueorangutan package

blueorangutan · 2026-09-18T07:48: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-09-18T08:46:20Z

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

harikrishna-patnala

very minor comments added @shwstppr , can you please check them.

I've not verified all of the error labels and strings but checked the logic in implementing them. looks good so far. Thank you.

harikrishna-patnala · 2026-09-28T05:34:59Z

    private String errorText = "Command failed due to Internal Server Error";

+    @SerializedName("errortextkey")
+    @Param(description = "the key for the text associated with this error", since = "4.24.0")


change the version to 4.22.2 !!

Signed-off-by: Abhishek Kumar <[email protected]>

shwstppr · 2026-10-05T12:08:16Z

@blueorangutan package

blueorangutan · 2026-10-05T12:10:05Z

@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-10-05T13:15:03Z

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

harikrishna-patnala · 2026-10-05T14:12:34Z

@@ -0,0 +1,732 @@
+{


Apologies @shwstppr I missed reviewing this file.

Is it possible to group these labels somehow ? may be group them by resources and APIs like we have the APIs here https://cloudstack.apache.org/api/apidocs-4.23/

I'm thinking in terms of ease of use to the admins.

@harikrishna-patnala that won't be possible due a couple of reasons:

There is not always 1:1 mapping between the API and the error message. Many APIs may use the same underlying method, returning same message

For the above reason, we are using the error key structure defined here, https://cwiki.apache.org/confluence/spaces/CLOUDSTACK/pages/406618482/Error+Message+Consistency+Customization+and+Localization+Framework#ErrorMessageConsistency%2CCustomization%2CandLocalizationFramework-TemplateFormat. So essentially error messages are grouped with resource type and actions

Also, with the recent changes, operator can use multiple error message JSON files and group desired keys in different files for override which is defined here, https://cwiki.apache.org/confluence/spaces/CLOUDSTACK/pages/406618482/Error+Message+Consistency+Customization+and+Localization+Framework#ErrorMessageConsistency%2CCustomization%2CandLocalizationFramework-PluginandOperatorOverrides and also in doc PR

github-actions · 2026-10-05T14:41:11Z

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

github-actions · 2026-10-05T14:48:14Z

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

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

shwstppr removed the status:has-conflicts label Apr 14, 2026

sureshanaparti removed this from Apache CloudStack 4.22.1 Apr 24, 2026

sureshanaparti removed this from the 4.22.1 milestone Apr 24, 2026

shwstppr added 5 commits September 15, 2026 09:50

wip

af19de9

allow plugin specific error messages files

8786931

Signed-off-by: Abhishek Kumar <[email protected]>

allow configuration for behaviour

0e4db7f

Signed-off-by: Abhishek Kumar <[email protected]>

add smoke test

45efa6d

Signed-off-by: Abhishek Kumar <[email protected]>

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

e669190

shwstppr mentioned this pull request Sep 18, 2026

notes for improve error messaging apache/cloudstack-documentation#684

Draft

shwstppr added 4 commits September 18, 2026 11:41

add documentation

b99c315

Signed-off-by: Abhishek Kumar <[email protected]>

fixes and admin only variant

eff68e0

Signed-off-by: Abhishek Kumar <[email protected]>

fix builds

3102fda

Signed-off-by: Abhishek Kumar <[email protected]>

fix missing license

b4034b8

Signed-off-by: Abhishek Kumar <[email protected]>

harikrishna-patnala reviewed Sep 28, 2026

View reviewed changes

shwstppr added 5 commits September 28, 2026 16:19

update version

2fdc492

Signed-off-by: Abhishek Kumar <[email protected]>

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

8602340

fic build

1805cce

Signed-off-by: Abhishek Kumar <[email protected]>

Merge branch '4.22' into improve-error-messages

c063fc4

fix failing test

f6fc9ad

Signed-off-by: Abhishek Kumar <[email protected]>

harikrishna-patnala reviewed Oct 5, 2026

View reviewed changes

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!

github-actions Bot commented Mar 26, 2026

Uh oh!

shwstppr commented Sep 3, 2026

Uh oh!

blueorangutan commented Sep 3, 2026

Uh oh!

blueorangutan commented Sep 3, 2026

Uh oh!

github-actions Bot commented Sep 10, 2026

Uh oh!

shwstppr commented Sep 18, 2026

Uh oh!

blueorangutan commented Sep 18, 2026

Uh oh!

blueorangutan commented Sep 18, 2026

Uh oh!

harikrishna-patnala left a comment

Choose a reason for hiding this comment

Uh oh!

harikrishna-patnala Sep 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shwstppr commented Oct 5, 2026

Uh oh!

blueorangutan commented Oct 5, 2026

Uh oh!

blueorangutan commented Oct 5, 2026

Uh oh!

harikrishna-patnala Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

shwstppr Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 5, 2026

Uh oh!

github-actions Bot commented Oct 5, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

shwstppr commented Dec 24, 2025 •

edited

Loading

codecov Bot commented Dec 24, 2025 •

edited

Loading