Errors and diagnostics

On this page6

1Overview
2In the app
3In the CLI
4Error codes
5Warnings
6CLI codes

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 the SQL of Athena and Amazon Aurora DSQL operations. Dynomate also removes the SQL from the detail and hint of an Aurora DSQL error.
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, AWS Region, table ARN, cluster ARN or database role 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.
A failed Aurora DSQL operation can also show a commit: line. See Cancel a run.

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", or "1.1" for a request with an Aurora DSQL operation.
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. Aurora DSQL operations do not accept endpointUrl, database or tableArn. 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 or clusterArn. 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, an expression in consistentRead, and an Aurora DSQL parameter that is a set. Fix: Give the expected type, or use a cast. For an Aurora DSQL parameter, use a list, not a set.
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_INVALID_CLUSTER_REFERENCE: clusterArn is not a valid Aurora DSQL cluster ARN. A missing clusterArn is DNML_MISSING_FIELD. Fix: Use the form arn:aws:dsql:<region>:<account-id>:cluster/<cluster-id>. See Connection keys.
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. Dynomate 2.0 rejects Aurora DSQL operations with this code. Dynomate CLI 0.0.21 and earlier also reject them. Fix: Use an operation from the operation reference and a "file" export target. For Aurora DSQL operations, update the app and the CLI.

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. For Aurora DSQL, details.commitStatus can be committed, rolled-back or unknown. The 5-minute transaction limit of Aurora DSQL gives DNML_AWS, not this code. Fix: Increase timeoutMs, or reduce the work. Dynomate does not roll back completed writes. If commitStatus is unknown, check the data before you run the request again.
DNML_CANCELLED: You canceled the run or the operation, for example with Cancel in the request toolbar or Ctrl+C in the CLI. For Aurora DSQL, details.commitStatus can be committed, rolled-back or unknown. Fix: If commitStatus is unknown, check the data first. Then 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. Aurora DSQL errors keep DNML_AWS, and awsError.awsErrorCode is the SQLSTATE. Their details can have sqlState, dsqlCode (for example OC000), detail, hint, position, statementIndex, attempts, commitStatus and transactionEndedAt. They have no AWS request ID. Fix: Read the AWS details: the AWS error code, request ID and HTTP status. For AccessDenied, see Permission errors. For Aurora DSQL, see Aurora DSQL errors and limits.
DNML_IO: The export file already exists, Dynomate cannot read or write it, or Dynomate cannot register the snapshot. For Aurora DSQL, Dynomate cannot read the network settings from the app database. Fix: Check the path, free space and permissions, or use a new file name. For Aurora DSQL, check the app data directory and its permissions.
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.
DNML_DSQL_TRANSACTION_OPEN: The SQL of a dsql.query left a transaction open on the connection of this run. Its changes are not committed. Fix: Run COMMIT in a later operation on the same connection. If no operation commits, the transaction rolls back when the run ends.
DNML_DSQL_TRANSACTION_ENDED: A statement in a dsql.transaction ran COMMIT or ROLLBACK. Later statements ran outside the transaction. Fix: Check which changes stayed. Remove the statement, or make it the last one.

CLI codes

Before validation, the CLI reports these codes in error when it checks the app database, 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. To migrate in the app, see Migrate legacy collections.
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.
APP_DATA_SCHEMA_UNSUPPORTED: A newer Dynomate app updated the app database, and this CLI version cannot read it. Each requests run fails. Fix: Update the CLI. See Compatibility with the desktop app.
APPROVAL_FAILED: The request needs approval, but there is no terminal, or the user declined. Fix: Run the CLI in a terminal. In automation, review the request first, then use --approval=never. See Approval in automation.