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:

{
	"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.

Error message keys follow a structured, hierarchical naming convention to ensure consistency, readability, and easy discoverability.

The general format is:

<actionable_resource>.<action>.<failing_resource_or_entity>.<cause_and_context>...

Where:

• actionable_resource
  The primary resource or feature being acted upon
  (e.g., vm, volume, network, template)

• action
  The operation being performed
  (e.g., deploy, start, attach, detach, update)

• failing_resource_or_entity
  The resource or entity that caused the failure
  (e.g., serviceoffering, diskoffering, host, cluster, ip)

• cause and context
  The specific reason for the failure
  (e.g., not.found, inactive, invalid, conflict, unsupported)

Templates support placeholder substitution using {{placeholder}} syntax.

Admin-specific variants are supported by adding a .admin suffix to the key.

Example:

{
	"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.

Localization

Localization of error messages is handled at the client side.

The CloudStack management server returns a stable error message key (errortextkey) along with contextual metadata (errormetadata). Clients are expected to resolve this key into a localized, user-facing message.

CloudStack UI Localization

When using the official CloudStack UI:

• Localized messages for error message keys can be added to the existing UI locale files.

• Each locale file maps error message keys to translated message templates.

• Placeholders in the localized templates are substituted using values from errormetadata.

This approach:

• Keeps localization concerns out of the management server.

• Allows UI translations to evolve independently.

• Enables consistent localization across API consumers.

Other API Clients

Other API clients (CLI tools, SDKs, external integrations) may:

• Maintain their own localization mappings for error message keys, or

• Fall back to using the server-provided errortext if localization is not implemented.

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.