h2. 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.

h2. 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.

h2. 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.

h2. High-Level Design

h3. 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

h3. 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}
{
"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: ...)"
}
}
}
{code}

h2. Error Message Templates

h3. 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.

h3. 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}
{
"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."
}
{code}

h2. 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.

h2. 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.

h2. 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.

h2. 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.

h2. 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.

h2. 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.

h2. 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.

h2. 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.