CLI error codes

Messagevisor commands that support --json report failures using an envelope like this:

{
  "error": {
    "code": "unknown_target",
    "message": "Unknown target \"mobile\".",
    "details": {
      "target": "mobile"
    }
  }
}

Automation should branch on error.code, while treating error.message as human-readable text. The details object is useful for diagnostics, but its fields can grow over time. The codes below are the stable vocabulary for built-in commands.

General input and option errors#

Code	Meaning
`invalid_cli_arguments`	Command-line arguments could not be parsed or validated.
`missing_required_option`	A required option was not provided.
`conflicting_options`	Mutually exclusive options were provided together.
`invalid_option`	An option value is not valid for the command.
`invalid_input`	The supplied input cannot be used for the requested operation.
`invalid_json`	JSON input could not be fetched, parsed, or selected.
`invalid_csv`	CSV input is malformed or missing required columns.
`invalid_format`	A format name or output format is not supported.
`invalid_regular_expression`	A regular expression option could not be compiled.
`invalid_configuration`	`messagevisor.config.js` is invalid.
`invalid_project_configuration`	The CLI could not load the project configuration.
`invalid_entity_key`	An entity key does not follow the configured naming rules.
`invalid_entity_path`	A source path uses a reserved character or escapes its configured directory.
`entity_already_exists`	A destination file or entity already exists.
`entity_not_found`	A requested file or entity does not exist.

Entity and project selection errors#

Code	Meaning
`unknown_locale`	The requested locale is not defined.
`unknown_message`	The requested message is not defined.
`unknown_target`	The requested target is not defined.
`unknown_attribute`	The requested attribute is not defined.
`unknown_segment`	The requested segment is not defined.
`unknown_format`	The requested format is not defined.
`unknown_set`	The requested set is not defined.
`no_sets`	Sets are enabled but none are available.
`sets_not_enabled`	A set option was used in a project without sets enabled.
`set_required_for_json`	A sets-based JSON command needs an explicit `--set`.
`no_matching_messages`	A message filter matched no source messages.
`missing_locale`	A message cannot be created until a locale exists.

Promotion and workflow errors#

Code	Meaning
`promotion_not_allowed`	The configured promotion flow does not allow the requested path.
`promotion_preflight_failed`	Source or destination definitions failed the promotion preflight lint.
`promotion_conflict`	Promotion was stopped because `--conflicts=fail` found conflicts.
`invalid_conflict_strategy`	The promotion conflict policy is not `source`, `destination`, or `fail`.
`invalid_audit_format`	The promotion audit format is not supported.
`invalid_override`	An override is invalid for promotion.
`duplicate_override`	A message contains duplicate override keys.
`json_pretty_not_supported`	`build --json` was combined with `--pretty`; build JSON is NDJSON.

Git, initialization, and editorial errors#

Code	Meaning
`unknown_command`	The requested CLI command is not registered.
`duplicate_cli_command`	A built-in or plugin command was registered more than once.
`missing_git_ref`	No default Git comparison ref could be found.
`git_ref_not_found`	A requested Git ref is not available in the checkout.
`git_command_failed`	A Git command failed while preparing a comparison.
`project_not_found`	A project or project archive could not be found.
`invalid_project_path`	The project is outside the expected Git repository.
`download_failed`	An initialization download failed.
`entity_conflict`	An editorial mutation was based on a stale file version.
`duplicate_mutation`	A mutation batch contains the same entity more than once.
`editorial_mutation_in_progress`	Another editorial mutation currently owns the project lock.

cli_error is the compatibility fallback for an unclassified error from a plugin. internal_error is reserved for unexpected errors that are not represented by a built-in validation path.