{"record":{"id":"6afc32800e4705fc","repo":"apache/seatunnel","slug":"common-33","errorCode":"COMMON-33","errorMessage":"The datetime format '<datetime>' of field '<field>' is not supported. Please check the datetime format.","messagePattern":"The datetime format '<datetime>' of field '<field>' is not supported\\. Please check the datetime format\\.","errorType":"error_code","errorClass":"SeaTunnelRuntimeException","httpStatus":null,"severity":"error","filePath":"seatunnel-formats/seatunnel-format-csv/src/main/java/org/apache/seatunnel/format/csv/CsvDeserializationSchema.java","lineNumber":391,"sourceCode":"                    CommonErrorCode.UNSUPPORTED_DATA_TYPE,\n                    String.format(\n                            \"SeaTunnel can not parse this date format [%s] of field [%s]\",\n                            field, fieldName));\n        }\n        TemporalAccessor parsedTimestamp = dateTimeFormatter.parse(field);\n        return LocalDateTime.of(\n                parsedTimestamp.query(TemporalQueries.localDate()),\n                parsedTimestamp.query(TemporalQueries.localTime()));\n    }\n\n    private OffsetDateTime parseTimestampTz(String field, String fieldName) {\n        try {\n            return OffsetDateTime.parse(field, DateTimeFormatter.ISO_OFFSET_DATE_TIME);\n        } catch (DateTimeParseException ignored) {\n            // Fallback: data written by old SeaTunnel (wall-clock, no offset).\n            DateTimeFormatter fallbackFmt = DateTimeUtils.matchDateTimeFormatter(field);\n            if (fallbackFmt == null) {\n                throw CommonError.formatDateTimeError(field, fieldName);\n            }\n            TemporalAccessor ta = fallbackFmt.parse(field);\n            return LocalDateTime.of(\n                            ta.query(TemporalQueries.localDate()),\n                            ta.query(TemporalQueries.localTime()))\n                    .atOffset(ZoneOffset.UTC);\n        }\n    }\n}\n","sourceCodeStart":373,"sourceCodeEnd":401,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-formats/seatunnel-format-csv/src/main/java/org/apache/seatunnel/format/csv/CsvDeserializationSchema.java#L373-L401","documentation":"CsvDeserializationSchema.parseTimestampTz parses a CSV field into an OffsetDateTime, first trying ISO_OFFSET_DATE_TIME and, on failure, falling back to DateTimeUtils.matchDateTimeFormatter for legacy wall-clock timestamps written without a zone offset (assumed UTC). If neither the ISO pattern nor any known fallback pattern matches, CommonError.formatDateTimeError is thrown with the value and field name. The timestamp string uses a format outside both the ISO-offset form and the supported fallback patterns.","triggerScenarios":"Reading a CSV column mapped to TIMESTAMP_WITH_TIME_ZONE where the cell text is neither an ISO-8601 offset datetime (e.g. '2024-01-01T10:00:00+01:00') nor one of the matched legacy datetime patterns — e.g. '2024/01/01 10:00:00 UTC', epoch millis as text, or truncated strings like '2024-01-01 10'.","commonSituations":"CSVs exported by tools with locale timestamp formats or non-standard zone names; numeric epoch timestamps stored in a column typed TIMESTAMP_WITH_TIME_ZONE; partially truncated timestamps from fixed-width exports; mixed formats within one column where the first rows parse but later rows fail.","solutions":["Check the failing datetime string in the error message and identify its actual pattern vs ISO offset form.","Normalize the CSV timestamps to ISO-8601 with offset, e.g. '2024-01-01T10:00:00Z' or '2024-01-01T10:00:00+08:00'.","If the column is epoch millis or a custom pattern, type it appropriately (BIGINT) or convert it with a transform before the CSV deserialization/consumption.","If the column has no meaningful offset, use TIMESTAMP (without time zone) as the column type so the wall-clock fallback path applies instead."],"exampleFix":"// before\nrow: 2024/01/01 10:00 AM  -> formatDateTimeError\n// after (fix CSV cell)\nrow: 2024-01-01T10:00:00+08:00\n// or change column type if no offset exists\ncolumn { ts = TIMESTAMP } // wall-clock fallback handled as UTC","handlingStrategy":"validation","validationCode":"// validate a sample timestamp cell parses as ISO offset before running the job\ntry {\n  java.time.OffsetDateTime.parse(sampleCell, java.time.format.DateTimeFormatter.ISO_OFFSET_DATE_TIME);\n} catch (java.time.format.DateTimeParseException e) {\n  System.err.println(\"Not ISO-offset datetime: \" + sampleCell);\n}","typeGuard":null,"tryCatchPattern":"try {\n  SeaTunnelRow row = deserializationSchema.deserialize(line);\n} catch (org.apache.seatunnel.api.common.SeaTunnelRuntimeException e) {\n  // COMMON-33: capture payload for repair/replay\n  LOG.warn(\"Bad timestamp in CSV line: {}\", e.getFormattedMessage());\n}","preventionTips":["Write timestamps in ISO-8601 with explicit offset ('Z' or +/-HH:MM) at export time","If data is wall-clock only, declare the column TIMESTAMP (no tz) so the legacy fallback applies","Avoid storing epoch millis in datetime-typed columns; use BIGINT and convert explicitly","Validate a sample of each column's format during onboarding of new CSV sources"],"tags":["csv","timestamp","timezone","deserialization"],"backgroundTag":"invalid-date-format","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}