Errors and diagnostics

Each DNML problem has a stable code and a message. Find what a code means and what to do.

A problem in the file also has a location: the file, line, column, operation and field.
Messages never show secret variable values or raw Athena SQL. Dynomate shortens S3 output paths to the bucket and the last part of the key.

In the App

When you edit a request:

The Operations rail and each operation tab show the number of issues.
Select a file diagnostic above the workbench to go to its field.
Problems with the profile, region or table ARN show under the operation header.
If the editor cannot show the file, select Reveal file and correct it in a text editor.

When you run the request:

If validation fails, the results panel shows the diagnostics, and no operation runs.
A failed operation row shows CODE: message. Expand the row, then open Metadata for the details and warnings.
Request errors, for example a timeout, show above the operation rows.
A failed Batch write shows the result of each write under Diagnostic result in Data.

In the CLI

requests run prints the result to stdout, also when the request fails.

The pretty format prints CODE: message, then at file:line:column if the location is known. Warnings show on warning: lines.
With --format=json, the request error has code, message and details. For a validation error, details has the location.
Each failed operation has outcomes[].error with code and message. It can also have awsError and details.
If validation fails, the CLI shows only the first diagnostic. To see all diagnostics, open the request in the app.

The exit code is 1 if the request fails, and 2 if the arguments are not valid.

Error Codes

Checked Before Anything Runs

Validation reports these codes. Each one stops the request before the first AWS call.

DNML_SYNTAX: The file is not valid TOML, or an expression has an unclosed ${, an unknown function or an unknown cast. Fix: Correct the reported line, and write casts in lowercase.
DNML_UNSUPPORTED_VERSION: The major version in version is not 1. Fix: Set version = "1.0".
DNML_SCHEMA: The file breaks a structure rule that has no specific code, for example a version that is not MAJOR.MINOR. Fix: Compare the reported field with the operation reference.
DNML_MISSING_FIELD: A required key is missing, for example name, or all update expression keys of an Update item. Fix: Add the key that the operation reference marks Required.
DNML_UNKNOWN_KEY: The table or operation has no such key, for example a typo or tableName on a DynamoDB operation. Fix: Remove or rename the key. In the app, use Unrecognized fields.
DNML_DUPLICATE_OPERATION: Two operations have the same normalized name. Fix: Rename one of the operations.
DNML_ROOT_COLLISION: A variable has the same name as the normalized name of an operation. Fix: Rename the variable or the operation.
DNML_UNKNOWN_DEPENDENCY: dependsOn names an operation that is not in the request. Fix: Use the exact display name of the operation, not its normalized name.
DNML_DEPENDENCY_CYCLE: Operations depend on each other in a loop. Fix: Remove one dependsOn entry.
DNML_REGION_MISMATCH: The region of the operation or [defaults] is not the region in tableArn. Fix: Remove region, or make it match the ARN.

Checked Before or During a Run

Validation reports these codes if it knows the value. Otherwise, the operation fails with the code before it calls AWS.

DNML_TYPE_MISMATCH: A value has the wrong type, or a cast rejects it. Examples are "1.5" or " 5" cast to integer, and an expression in consistentRead. Fix: Give the expected type, or use a cast.
DNML_UNRESOLVED_TEMPLATE: An expression refers to an unknown variable, a missing path or a failed or skipped operation, or a connection key is empty. Fix: Check the variable names, the selected environments and the earlier results.
DNML_TYPED_VALUE: A typed value is not valid, for example { N = 5 } instead of { N = "5" }. Fix: Give S and N string values, with a cast if necessary.
DNML_INVALID_TABLE_REFERENCE: tableArn is missing or is not a valid DynamoDB table ARN. Fix: Use the form arn:aws:dynamodb:<region>:<account-id>:table/<table-name>.
DNML_INSECURE_ENDPOINT: endpointUrl uses plain HTTP for a host that is not localhost or a loopback address. Fix: Use HTTPS or a loopback address.
DNML_UNSUPPORTED_OPERATION: Dynomate does not support the operation type or the export target, for example an S3 export target. Fix: Use an operation from the operation reference and a "file" export target.

Reported During a Run

These codes fail one operation. Its onError key sets what happens next. See Error policy.

DNML_GUARD_FAILED: The table name or item count does not match a Delete table or Truncate table guard, so Dynomate deletes nothing. Fix: Make sure that the request targets the correct table before you change the guard.
DNML_IMPORT_PREFLIGHT: The import source failed its checks, so Dynomate wrote nothing. The message names each problem: invalid-attribute-value, missing-partition-key, missing-sort-key, invalid-key-type, key-too-large, duplicate-key or same-source-and-destination. Fix: Correct the reported items, or use a different source table.
DNML_UNPROCESSED_ITEMS: A Batch get or Batch write has unprocessed keys or writes after its retries. Fix: Before you run a Batch write again, read writeOutcomes to find the unconfirmed writes.
DNML_TIMEOUT: An operation or request deadline expired, and the error details include any known Athena query execution ID. Fix: Increase timeoutMs, or reduce the work. Dynomate does not roll back completed writes.
DNML_CANCELLED: You canceled the run or the operation, for example with Cancel in the app or Ctrl+C in the CLI. Fix: Run the request again. Dynomate does not roll back completed writes.
DNML_AWS: AWS or the network returned an error. If AWS gives an error code, for example ConditionalCheckFailedException, Dynomate shows that code instead. Fix: Read the AWS details: the AWS error code, request ID and HTTP status.
DNML_IO: The export file already exists, Dynomate cannot read or write it, or Dynomate cannot register the snapshot. Fix: Check the path, free space and permissions, or use a new file name.
DNML_EXECUTION: A Truncate table worker stopped unexpectedly. Fix: Run the operation again. Deleted items stay deleted.

Warnings

Warnings do not fail an operation.

DNML_ROOT_SHADOWED: An environment variable or --input value has the normalized name of an operation. After the operation succeeds, expressions use its result, not the input. Fix: Rename the input or the operation.
csv-values-imported-as-strings: The import source is CSV, so Dynomate wrote each value as a string. Fix: Use a JSON or JSON Lines source for other types.

CLI Codes

Before validation, the CLI reports these codes in error when it loads files, environments and profile settings, or asks for approval.

MIGRATION_REQUIRED: The collection uses the legacy request format. Fix: Migrate the collection with the command in the message.
FILE_ERROR: The CLI cannot read a request, marker or environment file. Fix: Check the path and file permissions.
ENVIRONMENT_NOT_FOUND: The environment in --global-env or --collection-env does not exist. Fix: Check the environment name and the app data directory.
ENVIRONMENT_LOAD_FAILED: The CLI cannot load the selected global environment. Fix: Check the app data directory and its permissions.
ENVIRONMENT_INVALID: A collection environment file does not contain valid environment data. Fix: Correct the file, or create the environment again in the app.
PROFILE_LOAD_FAILED: The CLI cannot load saved profile settings from the app data directory. Fix: Check the app data directory and its permissions.
APP_DATA_UNAVAILABLE: The CLI cannot find an app data directory. Fix: Set DYNO_APP_DATA_DIR.
APPROVAL_FAILED: The request needs approval, but there is no terminal, or the user declined. Fix: Run the CLI in a terminal, or approve the request in advance with --approval=never.