Skip to content

Errors and Warnings

themarioga edited this page Nov 8, 2026 · 1 revision

Errors and Warnings

TIE reports problems at three levels. The codes and type names below are a stable contract: changing one is a breaking change. Messages are English text that may be reworded.

Level Where Effect
Configuration ConfigurationException.getProblems() Thrown before any file is touched
Line LineRejection.errors(): LineError{field, code, args, message} The line is not applied; the file goes on
File or run FileResult.error() / ImportResult.error() / ExportResult.error(): FileError{type, message, rowNumber, lineNumber} The file fails and the run stops

Warnings (Warning{code, message, fileName}) never change an outcome.

Line errors

Argument values are text; an argument without a value is absent.

code Field args message
NO_TRANSLATION yes value value '{value}' has no translation
REQUIRED_EMPTY yes — required field is empty
INVALID_TYPE yes value, type, format (if any) value '{value}' is not a valid {type}
TOO_LONG yes value, maxLength value is longer than {maxLength}
TOO_SHORT yes value, minLength value is shorter than {minLength}
PATTERN_MISMATCH yes value, regex value '{value}' does not match {regex}
NOT_ALLOWED yes value, allowedValues (joined with ,) value '{value}' is not allowed
DEFAULT_UNRESOLVABLE yes template default value has placeholders and no resolver is registered
DEFAULT_RESOLVER_FAILED yes template, exceptionMessage default value resolver failed: {exceptionMessage}
TRANSFORMER_FAILED yes transformer, exceptionMessage transformer '{transformer}' failed: {exceptionMessage}
PARENT_REJECTED no parentLineNumber parent rejected
CONSUMER_REJECTED no reason {reason}
CONSUMER_FAILED no exceptionMessage {exceptionMessage}

exceptionMessage is the exception's message, or its simple class name when it has none. LineRejection also carries lineNumber, rowNumber, layout, sourceFileName, parentLineNumber and the rawValues of the line as read, before any engine step.

File and run errors

type When
STRUCTURAL Malformed CSV/XML/JSON; header that does not match in HEADER mode; undeclared repeated element or array; missing sheet
ENCODING Bytes that are not valid in the declared encoding (rowNumber is the physical row)
UNSAFE_CONTENT XML with a DOCTYPE; XLSX above the compression limits
EXTENSION_NOT_ALLOWED The extension is not in the layout's allowedFormats
FILE_TOO_LARGE Above the channel's maxFileSize
DUPLICATE_TIMESTAMP Two candidates of a layout with the same timestamp (run level)
AMBIGUOUS_LAYOUT A name matches several layouts (run level)
CHANNEL Network, I/O or timeout errors; a file that disappeared
AUTHENTICATION SFTP credentials rejected, or the SecretProvider failed
HOST_KEY SFTP host key verification failed
NAME_COLLISION The destination name exists and onExistingFile = FAIL
THRESHOLD Rejections above the threshold
CONSUMER The consumer threw with consumerErrorPolicy = ABORT_FILE
HOOK A FileHook method threw

Warnings

code When
HEADER_MISMATCH POSITION: a header name differs from the field at that column
EXTRA_COLUMNS POSITION: more columns than fields; HEADER: a column without header name
MISSING_COLUMN LETTER: a letter beyond the file's columns
UNSAFE_FILE_NAME A listed name with /, \ or ..; it is ignored
POST_ACTION_FAILED The move or delete after a successful file failed
REPORT_FAILED A result report could not be written or delivered
LISTENER_FAILED A RunListener method threw
TEMP_CLEANUP_FAILED A temporary or working file could not be deleted

Programming against the codes

for (LineError error : rejection.errors()) {
    switch (error.code()) {
        case NO_TRANSLATION -> unknownCodes.add(error.args().get("value"));
        case REQUIRED_EMPTY -> missing.add(error.field());
        default -> log.info("{} {}", error.field(), error.message());
    }
}

The test suite produces every code, type and warning through the public API and checks their argument names.

Clone this wiki locally