DUE TO SPAM, SIGN-UP IS DISABLED. Goto Selfserve wiki signup and request an account.
Page History
...
Summary
CloudStack currently generates many API error messages through ad-hoc string construction, leading to inconsistencies, limited customization, and no clear support for localization.
This feature introduces a structured, key-based error messaging framework where the management server emits a stable error message key along with contextual metadata. Clients and operators can use these to present consistent, customizable, and localized error messages.
...
Goals
Provide consistent and stable error messages using predefined keys.
Allow operators to customize error message templates without rebuilding CloudStack.
Enable client-side localization using error message keys and metadata.
Support role-aware error messages, allowing more detailed messages for admin users.
Maintain backward compatibility with existing API clients.
...
Non-Goals
Converting all existing CloudStack errors in a single release.
Introducing a full server-side localization framework for all languages.
Changing existing API error codes or response structures beyond adding new fields.
...
High-Level Design
...
Error Message Keys and Metadata
Errors are identified using a unique error message key (for example,
...
vm.deploy.serviceoffering.inactive
...
) and accompanied by a metadata map containing contextual information such as IDs, names, or related objects.
Instead of hard-coded strings, exceptions are raised with:
an error message key
optional metadata describing the error context
...
API Response Changes
API error responses include the following additional fields:
errortextkey – the stable error message key
errormetadata – a map of contextual values
The existing errortext field is preserved for backward compatibility.
Example:
...
| Code Block |
|---|
...
{ |
...
"deployvirtualmachineresponse": { |
...
"errorcode": 431, |
...
"cserrorcode": 4350, |
...
"errortext": "Unable to deploy Instance as the given service offering 'test' (ID: 13, UUID: ...) is inactive. Specify an active service offering.", |
...
"errortextkey": "vm.deploy.serviceoffering.inactive", |
...
"errormetadata": { |
...
"serviceOffering": "'test' (ID: 13, UUID: ...)" |
...
} |
...
} |
...
}
|
...
Error Message Templates
...
Template Source
Error message templates are stored in a JSON file on the management server:
...
/etc/cloudstack/management/error-messages.json
...
The default file is shipped with CloudStack and operators may modify it to customize messages.
...
Template Format
Each entry maps an error message key to a message template.
Templates support placeholder substitution using {{
...
placeholder}}
...
syntax.
Admin-specific variants are supported by adding a
...
.admin
...
suffix to the key.
Example:
...
| Code Block |
|---|
...
{ |
...
"vm.deploy.serviceoffering.inactive": |
...
"Unable to deploy Instance as the given service offering {{serviceOffering}} is inactive. Specify an active service offering.", |
...
"vm.deploy.serviceoffering.inactive.admin": |
...
"Unable to deploy Instance as service offering {{serviceOffering}} is inactive. Please activate it or choose a different offering." |
...
}
|
...
ErrorMessageResolver
A new component, ErrorMessageResolver, is responsible for resolving error message keys into user-facing messages.
Responsibilities:
Load and cache error message templates from
...
error-messages.json
...
.
Automatically reload templates when the file is modified.
Select admin-specific templates when the caller is a root admin.
Substitute placeholders using values from error metadata.
Convert domain objects in metadata into user-friendly string representations.
...
Role-Aware Error Messages
The caller’s role is determined using CallContext.
If the caller is a root admin and an admin-specific template exists, it is used; otherwise, the default template is applied.
...
Exception Handling Changes
Common exceptions (such as
...
CloudRuntimeException
...
and
...
ServerApiException
...
) are enhanced with constructors that accept:
error message key
metadata map
During API response generation:
The error message key and metadata are added to the response.
The resolved message is used to populate errortext.
...
Initial Scope
The initial implementation applies this framework to selected validation paths in the VM deployment flow.
Additional flows and modules can be incrementally migrated in future releases.
...
Backward Compatibility
Existing clients can continue using errortext as before.
New clients may prefer errortextkey and errormetadata for localization and structured handling.
No existing API fields are removed or modified.
...
Packaging and Operations
...
error-messages.json
...
is installed as a configuration file and not overwritten during upgrades.
Operators may customize messages locally.
In multi-management-server setups, operators must ensure the file is kept in sync across all nodes.
...
Testing Strategy
Unit tests for:
...
- template resolution and placeholder substitution
...
- admin vs non-admin template selection
...
- metadata object string conversion
Integration tests validating API responses include error message keys and metadata.
...
Future Enhancements
Gradual migration of additional API flows to the new framework.
Documentation for client-side localization using error message keys.
Optional tooling for validating or reloading error message templates at runtime.
Overview
Content Tools