Skip to content

Error Codes Reference

This document lists every diagnostic code emitted by tx, grouped by prefix. Codes are part of the public API surface — renaming or removing a code requires a major version bump (see cli-ux-guidelines.md).

JSON Error Envelope

Under --output-format json (or --error-format json), errors are emitted on stderr as a single JSON object using the first Error/Fatal diagnostic:

{
  "error": "Human-readable message describing what happened.",
  "code": "TOMIX_MUTATION_FAILED",
  "severity": "Error",
  "hint": "Optional guidance on how to fix the problem."
}

Fields:

Field Type Description
error string The diagnostic message. Always present.
code string The diagnostic code (see tables below). Always present.
severity string Info, Warning, Error, or Fatal.
hint string Optional fix suggestion. May be null.

Exit Codes

Code Meaning
0 Success.
1 General failure (most errors).
2 Usage/argument error, IO failure, or pre-condition violation.

Handlers override the default via TomixResult.Fail(..., exitCode: 2). If no exit code is specified, the default is 1. Command-line parse errors (unknown option, missing required argument, invalid option value) also exit 2.

Naming Convention

All diagnostic codes use uppercase SNAKE_CASE prefixed with TOMIX_. For example: TOMIX_MUTATION_SAVE_FAILED, TOMIX_OBJECT_NOT_FOUND.

Mutation Codes (TOMIX_MUTATION_*)

Emitted by MutationRunner and handlers that participate in the mutation lifecycle (add, rm, set, mv, replace, format, script, bpa run --fix, bpa rules ignore/unignore).

Code Exit Trigger
TOMIX_MUTATION_UNSUPPORTED_PROVIDER 1 The model provider does not implement IModelMutationSession.
TOMIX_MUTATION_UNSUPPORTED 1 A NotSupportedException was thrown during mutation.
TOMIX_ADD_OPTION_UNSUPPORTED 1 An add option was supplied for an object type that cannot consume it (e.g. --columns on a CalcGroup).
TOMIX_RENAME_BREAKS_REFS 1 --strict-refs was set and the rename (set -q name, mv) would leave DAX expressions referencing the old name. By default renames rewrite referencing DAX automatically, so this only fires for references that cannot be rewritten (role RLS filters) — or, under --no-fix-refs, for any reference. Without --strict-refs the rename proceeds with a warning listing the objects left broken.
TOMIX_RM_BREAKS_REFS 1 The object being removed (rm) is still referenced by DAX expressions. Unlike a rename there is nothing to rewrite, so the removal is blocked and the message lists the referencing objects; --force removes anyway and reports the now-broken references. Structural references (relationships, sort-by, hierarchy levels, perspective and translation entries, role permissions) never block — they are cascade-removed with the object.
TOMIX_MUTATION_INVALID_VALUE 1 An ArgumentException was thrown — invalid argument value.
TOMIX_MUTATION_FAILED 1 An InvalidOperationException was thrown — generic mutation failure.
TOMIX_MUTATION_SAVE_FAILED 2 An IOException occurred while saving the model.

Object Lookup Codes (TOMIX_OBJECT_*)

Emitted by get, deps, and format -p when a model object path fails to resolve.

Code Exit Trigger
TOMIX_OBJECT_NOT_FOUND 1 The object path matched zero objects. Includes a hint.
TOMIX_OBJECT_AMBIGUOUS 1 The object path matched more than one object.

BPA Codes (TOMIX_BPA_*)

Code Exit Trigger
TOMIX_BPA_INVALID_FAIL_ON 2 Invalid --fail-on value (expected: error, warning).
TOMIX_BPA_RULE_ID_REQUIRED 2 bpa rules ignore/unignore called without a rule id.
TOMIX_BPA_RULES_LOAD_FAILED 2 Failed to load the BPA rules catalog.
TOMIX_BPA_VIOLATIONS 1 BPA gate blocked the operation: violations found (or, under --fix-bpa, error-severity violations remained after auto-fix). Use --skip-bpa to bypass.

Staging Codes (TOMIX_STAGE_*)

Code Exit Trigger
TOMIX_STAGE_NOTHING_TO_COMMIT 1 stage commit called with no staged mutations.
TOMIX_STAGE_SOURCE_DRIFT 1 The staged model source has changed since staging.
TOMIX_STAGE_COMMIT_REMOTE_FAILED 1 Failed to deploy staged changes to the remote endpoint.
TOMIX_STAGE_COMMIT_LOCAL_FAILED 1 Failed to apply staged changes locally.
TOMIX_STAGE_MATERIALIZE_FAILED 1 Failed to materialize the working copy.
TOMIX_STAGE_OPTIONS_CONFLICT 2 Conflicting stage options (--revert combined with --save, --save-to, or --stage).
TOMIX_STAGE_SAVE_CONFLICT 2 Conflicting save options (e.g. --save and --stage together).
TOMIX_STAGE_NOTHING_STAGED 1 --revert called with no staged mutation for the model.
TOMIX_STAGE_MANIFEST_CORRUPT 2 A staged manifest exists but no longer parses (torn write, manual edit). Run tx stage discard to reset staging for the model.

Save Codes (TOMIX_SAVE_*)

Code Exit Trigger
TOMIX_SAVE_OUTPUT_REQUIRED 2 save called without an output path and none could be inferred.
TOMIX_SAVE_OUTPUT_EXISTS 2 The output path already exists (use --force to overwrite).
TOMIX_SAVE_FIX_UNSUPPORTED 2 save --fix is not supported by the provider.
TOMIX_SAVE_UNSUPPORTED_PROVIDER 1 The provider does not support model export/saving.
TOMIX_SAVE_UNSUPPORTED_SERIALIZATION 2 The requested serialization format is not supported.

Deploy Codes (TOMIX_DEPLOY_*)

Code Exit Trigger
TOMIX_DEPLOY_NO_TARGET 2 deploy called without a target server/database.
TOMIX_DEPLOY_UNSUPPORTED 2 The source model cannot be deployed (wrong provider/type).
TOMIX_DEPLOY_FIX_UNSUPPORTED 2 deploy --fix-bpa was requested but the provider session does not implement IModelMutationSession.
TOMIX_DEPLOY_INVALID_FLAGS 2 Contradictory deployment scope: --deploy-full combined with a granular --deploy-* flag, or a dependent flag without the one it refines (--deploy-policy-partitions without --deploy-partitions, --deploy-role-members without --deploy-roles).
TOMIX_DEPLOY_FAILED 1 The deployment operation failed.

Refresh Codes (TOMIX_REFRESH_*)

Code Exit Trigger
TOMIX_REFRESH_NO_REMOTE_TARGET 2 refresh could not resolve a remote endpoint (default connection is local and no remote workspace-mode secondary is set).
TOMIX_REFRESH_UNSUPPORTED 2 The provider session does not implement IModelRefreshSession (e.g. a local TMDL/BIM model).
TOMIX_REFRESH_BAD_TYPE 2 --type was not one of full, dataonly, automatic, calculate, clearvalues, defragment, add.
TOMIX_REFRESH_TABLE_PARTITION_CONFLICT 2 --table and --partition were passed together; choose one.
TOMIX_REFRESH_BAD_PARTITION 2 A --partition value was not formatted as TableName.PartitionName.
TOMIX_REFRESH_FAILED 1 The refresh command was rejected by the server (table not found, no permissions, etc.).

Query Codes (TOMIX_QUERY_*)

Code Exit Trigger
TOMIX_QUERY_REQUIRED 2 query called without -q, --file, or piped stdin.
TOMIX_QUERY_INPUT_CONFLICT 2 -q and --file were passed together; choose one.
TOMIX_QUERY_FILE_NOT_FOUND 2 The --file path does not exist.
TOMIX_QUERY_BAD_PARAM 2 A --param value was not formatted as name=value.
TOMIX_QUERY_OUTPUT_FORMAT 2 -o/--output-file could not resolve a json or csv format (pass --output-format json\|csv or use a .json/.csv extension).
TOMIX_QUERY_INVALID 2 The query does not start with EVALUATE, DEFINE, or SELECT; bypass with --no-validate.
TOMIX_QUERY_NO_REMOTE_TARGET 2 query could not resolve a live endpoint (default connection is local and no remote workspace-mode secondary is set).
TOMIX_QUERY_UNSUPPORTED 2 The provider session does not implement IModelQuerySession (e.g. a local TMDL/BIM model).
TOMIX_QUERY_FAILED 1 The query was rejected or failed on the server (DAX error, no permissions, timeout, etc.).

The performance options are best-effort and do not have dedicated error codes: --trace, --plan, and --cold all require admin rights on the endpoint (and are unavailable on shared-capacity Power BI). When they cannot be honored, tx query prints a one-line warning to stderr, still returns the rowset, and exits 0.

Regression Test Codes (TOMIX_TEST_*)

Emitted by test (DAX regression tests against a live model).

Code Exit Trigger
TOMIX_TEST_PATH_NOT_FOUND 2 The path argument does not exist.
TOMIX_TEST_NONE_FOUND 2 No .dax test files were found under the path (or none match --filter).
TOMIX_TEST_BAD_PARAM 2 A --param value was not formatted as name=value.
TOMIX_TEST_NO_REMOTE_TARGET 2 test could not resolve a live endpoint (default connection is local and no remote workspace-mode secondary is set).
TOMIX_TEST_UNSUPPORTED 2 The provider session does not support queries (e.g. a local TMDL/BIM model).
TOMIX_TEST_UPDATE_FAILED 1 An .expected.json snapshot could not be written during --update.

Test failures themselves carry no diagnostic code: a run whose tests fail (or are missing their snapshot) renders the full report and exits 1, mirroring bpa run. test also reuses TOMIX_NO_PROVIDER and TOMIX_AUTH_REQUIRED.

Incremental Refresh Codes (TOMIX_REFRESH_POLICY_*)

Emitted by incremental-refresh (show/set/rm/apply).

Code Exit Trigger
TOMIX_REFRESH_POLICY_NOT_FOUND 1 show/rm/apply targeted a table that has no incremental refresh policy.
TOMIX_REFRESH_POLICY_NO_OPTIONS 2 set called without any policy option (and without --revert); pass at least one, e.g. --rolling-window-periods.
TOMIX_REFRESH_POLICY_INVALID 1 set produced validation errors (missing range parameters, source expression not referencing RangeStart/RangeEnd, incoherent granularity/periods, incompatible compatibility level) and --force was not passed.
TOMIX_REFRESH_POLICY_UNSUPPORTED 2 apply targeted a session that is not XMLA-backed (partition generation runs on the server).
TOMIX_REFRESH_POLICY_APPLY_FAILED 1 The server rejected the apply operation.

incremental-refresh also reuses TOMIX_OBJECT_NOT_FOUND (table missing), TOMIX_REFRESH_NO_REMOTE_TARGET (apply with no remote endpoint), TOMIX_NO_PROVIDER, TOMIX_AUTH_REQUIRED, and the TOMIX_MUTATION_* / TOMIX_STAGE_* families via the shared mutation runner. Validation findings surfaced in the result payload (e.g. range_parameter_missing, granularity_order, no_polling_expression) are lowercase snake tokens, not TOMIX_ diagnostic codes.

VertiPaq Codes (TOMIX_VERTIPAQ_* / TOMIX_VPAX_*)

Code Exit Trigger
TOMIX_VERTIPAQ_UNSUPPORTED_SOURCE 2 The source is a local model definition (TMDL/BIM) with no live storage engine; connect to a deployed model or use --import.
TOMIX_VERTIPAQ_OPTIONS_CONFLICT 2 Conflicting options: --import with --export or --annotate, --obfuscate without --export, --save without --annotate, or csv output with multiple views.
TOMIX_VERTIPAQ_INVALID_FIELDS 2 --fields was combined with multiple views, or contained an unknown field token for the selected view.
TOMIX_VERTIPAQ_INVALID_TOP 2 --top was zero or negative; it must be a positive integer.
TOMIX_VERTIPAQ_TABLE_NOT_FOUND 1 The positional table filter matched no table in the statistics.
TOMIX_VERTIPAQ_FAILED 1 Statistics extraction against the live engine failed.
TOMIX_VPAX_READ_FAILED 2 The --import file is missing, unreadable, or not a valid statistics package.
TOMIX_VPAX_WRITE_FAILED 2 The --export target (or its obfuscation dictionary) could not be written.

Init Codes (TOMIX_INIT_*)

Code Exit Trigger
TOMIX_INIT_OUTPUT_REQUIRED 2 init called without an output path.
TOMIX_INIT_OUTPUT_EXISTS 2 The output path already exists.
TOMIX_INIT_UNSUPPORTED_SERIALIZATION 2 The requested serialization format is not supported for init.
TOMIX_INIT_UNSUPPORTED_COMPATIBILITY_MODE 2 The requested compatibility level is not supported.

Auth Codes (TOMIX_AUTH_*)

Note: Codes in this section are diagnostic codes, not environment variables. See Environment Variables for auth-related env vars.

Code Exit Trigger
TOMIX_AUTH_FAILED 1 Authentication failed (invalid credentials, token expired, etc.).
TOMIX_AUTH_REQUIRED 1 Authentication is required but no credentials were provided.
TOMIX_AUTH_SECRET_REQUIRED 2 A service-principal login needs a secret and none was provided: no source given, empty stdin under --password -, an empty secret file, or an empty interactive prompt.
TOMIX_AUTH_SECRET_SOURCE_CONFLICT 2 --password - and --password-file (or the certificate-password equivalents) were combined; choose one.
TOMIX_AUTH_SECRET_FILE_NOT_FOUND 2 The --password-file / --certificate-password-file path does not exist.

Script Codes (TOMIX_SCRIPT_*)

Code Exit Trigger
TOMIX_SCRIPT_FILE_NOT_FOUND 1 The script file was not found.
TOMIX_SCRIPT_REQUIRED 2 script called without a script file or inline script.

Config Codes (TOMIX_CONFIG_*)

Note: TOMIX_CONFIG_DIR is an environment variable, not a diagnostic code. See below.

Code Exit Trigger
TOMIX_CONFIG_INVALID_VALUE 2 config set called with an invalid value.
TOMIX_CONFIG_UNKNOWN_KEY 2 config set called with an unknown configuration key.

Profile Codes

Code Exit Trigger
TOMIX_PROFILE_NOT_FOUND 1 The named profile was not found.
TOMIX_PROFILE_NAME_REQUIRED 2 profile set called without a profile name.
TOMIX_NO_ACTIVE_CONNECTION 2 profile set --from-active called with no active connection.

Validate Issue Codes

Codes carried on the issues inside a validate result (not top-level diagnostics; the command exits 1 when any error-severity issue is present). DAX* codes come from the offline DAX reference scan; TOMIX_* codes come from structural integrity checks.

Code Severity Trigger
DAX0001 Error A DAX expression references a table that does not exist in the model.
DAX0002 Error A DAX expression references a column that does not exist on the named table (and no measure by that name exists).
DAX0003 Warning An unqualified [X] reference resolves to no measure or column anywhere in the model. Warning-severity because it may be a query-scoped extension column (ADDCOLUMNS/SUMMARIZE), which offline analysis cannot see.
TOMIX_BROKEN_RELATIONSHIP Error A relationship endpoint refers to a missing column.
TOMIX_BROKEN_SORT_BY Error A column's sort-by column does not exist on its table.
TOMIX_BROKEN_LEVEL Error A hierarchy level is bound to a column that does not exist on its table.
TOMIX_MODEL_LOAD_FAILED Error The model could not be opened or snapshotted at all (e.g. TMDL with unresolvable references); the provider's message is passed through.

General Codes

Code Exit Trigger
TOMIX_NO_PROVIDER 2 No registered provider can open the model.
TOMIX_PROVIDER_AMBIGUOUS 1 More than one registered provider claims the model reference. Provider CanOpen contracts are mutually exclusive, so this indicates a provider-registration bug, not a problem with the model.
TOMIX_MODEL_LOAD_FAILED 2 A provider matched the model but its source could not be loaded (unparsable TMDL/BIM, unresolvable references, unreadable file). The provider's message describes what failed; the command never ran.
TOMIX_NO_MODEL 2 No model reference was provided and none could be inferred.
TOMIX_CONNECT_FAILED 1 connect failed to establish a session.
TOMIX_INTERACTIVE_REQUIRED 1 An interactive-only flow (connect --remote, a valueless -w) was invoked without a TTY (e.g. --non-interactive, --quiet, redirected input, or json/csv output). Pass the workspace/model explicitly.
TOMIX_REMOTE_LIST_FAILED 1 Listing workspaces or models failed (Power BI REST or XMLA error) during an interactive connect.
TOMIX_DATABASE_NOT_FOUND 1 The database/model name was not found on the server.
TOMIX_DEPS_PATH_REQUIRED 2 deps called without an object path.
TOMIX_FIND_INVALID_REGEX 2 find --regex called with an invalid regular expression pattern.
TOMIX_UNKNOWN_OPTION 2 An unrecognized --option would have been bound to a positional argument (e.g. a typo'd flag). Put -- before positional values that must start with -.
TOMIX_MOVE_UNSUPPORTED 1 mv across tables called with an unsupported path shape; a cross-table move needs a Table/Measure source and destination. Moving a non-measure across tables surfaces as TOMIX_MUTATION_UNSUPPORTED from the provider.
TOMIX_MOVE_INVALID_PATH 2 mv source or destination is missing an object name (empty path, trailing /).
TOMIX_MOVE_NOOP 1 mv source and destination are identical; nothing to rename.
TOMIX_REPLACE_PATTERN_REQUIRED 2 replace called without a search pattern.
TOMIX_SET_PROPERTY_REQUIRED 2 set called without a property to set.
TOMIX_FORMAT_UNSUPPORTED_LANGUAGE 2 format called with an unsupported expression language.
TOMIX_FORMAT_FAILED 1 format --expression failed to format the inline expression (invalid DAX/M, or the formatter service was unreachable). The message includes the formatter's error details.
TOMIX_COMPLETION_UNSUPPORTED_SHELL 2 completion called with an unsupported shell name.
TOMIX_COMPLETION_SHELL_REQUIRED 2 completion called without its required shell argument.
TOMIX_PROFILE_TARGET_REQUIRED 2 A new profile has no usable remote, local-model, Desktop, or active-session target.
TOMIX_INVALID_OUTPUT_FORMAT 2 --output-format value is not one of: auto, text, json, csv, tmsl, bim, tmdl.
TOMIX_OUTPUT_FORMAT_UNSUPPORTED 2 The command cannot render the requested --output-format; the message lists the formats it supports.
TOMIX_CONFIG_CORRUPT 2 ~/.tomix/config.json exists but does not parse. Repair it manually or reset it with tx config init --force; help, version, doctor, and config recovery paths remain available.
TOMIX_UNEXPECTED 1 An unexpected exception reached the top-level handler. The stack trace is only printed under --debug; with --error-format json it is embedded as a detail field in the envelope so stderr stays valid JSON.

Update Codes (TOMIX_UPDATE_*)

Emitted by tx update (see docs/commands/manage.md). tx update --check exits 0 whether or not an update is available; these codes cover failures only.

Code Exit Trigger
TOMIX_UPDATE_CHECK_FAILED 1 Could not read the release list from api.github.com (network failure, or no releases published).
TOMIX_UPDATE_VERSION_NOT_FOUND 2 --version <v> names a version that is not a published release.
TOMIX_UPDATE_UNSUPPORTED_INSTALL 2 The running tx is not updatable in place (dev wrapper, or unrecognized install layout).
TOMIX_UPDATE_TOOL_FAILED 1 dotnet tool update -g Tomix.Cli exited non-zero.
TOMIX_UPDATE_DOWNLOAD_FAILED 1 The release asset or checksums.txt could not be downloaded.
TOMIX_UPDATE_CHECKSUM_MISMATCH 1 The downloaded asset's SHA-256 does not match checksums.txt; nothing was installed.
TOMIX_UPDATE_APPLY_FAILED 1 The binary swap failed (permissions, IO); the previous binary is restored.

Environment Variables

The following TOMIX_* tokens are environment variables, not diagnostic codes:

Variable Description
TOMIX_AUTH_CLIENT_ID Azure AD client id for service principal auth.
TOMIX_AUTH_TENANT Azure AD tenant id for service principal auth.
TOMIX_SESSION Session id for persisting the active model connection.
TOMIX_CONFIG_DIR Custom path to the configuration directory.
TOMIX_NO_UPDATE_CHECK Set (any value) to disable the throttled update check and notice.
TOMIX_POWERQUERY_FORMATTER_API Custom Power Query Formatter API endpoint URL.

Migration: Unified Mutation Error Codes

The following error codes were replaced by unified TOMIX_MUTATION_* codes. Scripts that pattern-match on the old codes should update to the new ones.

Old code New code
TOMIX_REPLACE_INVALID_ARGUMENT TOMIX_MUTATION_INVALID_VALUE
TOMIX_REPLACE_UNSUPPORTED TOMIX_MUTATION_UNSUPPORTED
TOMIX_REPLACE_FAILED TOMIX_MUTATION_FAILED
TOMIX_REPLACE_SAVE_FAILED TOMIX_MUTATION_SAVE_FAILED
TOMIX_SCRIPT_SAVE_UNSUPPORTED TOMIX_MUTATION_UNSUPPORTED
TOMIX_SCRIPT_SAVE_FAILED TOMIX_MUTATION_SAVE_FAILED
TOMIX_BPA_FIX_UNSUPPORTED TOMIX_MUTATION_UNSUPPORTED_PROVIDER
TOMIX_BPA_IGNORE_UNSUPPORTED TOMIX_MUTATION_UNSUPPORTED_PROVIDER

What did not change

Command-specific validation codes (checked before entering MutationRunner) are unchanged:

  • TOMIX_REPLACE_PATTERN_REQUIRED
  • TOMIX_SET_PROPERTY_REQUIRED
  • TOMIX_SCRIPT_FILE_NOT_FOUND
  • TOMIX_SCRIPT_REQUIRED
  • TOMIX_BPA_RULE_ID_REQUIRED
  • TOMIX_FORMAT_UNSUPPORTED_LANGUAGE