Page History

...

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.

...

• 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

...