apache/seatunnel · error · ConnectException

Source offset '" + key + "' parameter value " + obj + " coul

Error message

Source offset '" + key + "' parameter value " + obj + " could not be converted to a long

What it means

Offset.longOffsetValue() converts an offset map entry to a long (e.g. binlog filename position or LSN). If the stored value is neither a Number nor a parseable long string, it throws ConnectException. This guards against corrupted or foreign-format offset data in checkpoint state or startup-offset configuration.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/source/offset/Offset.java:53

 */
public abstract class Offset implements Comparable<Offset>, Serializable {

    private static final long serialVersionUID = 1L;

    @Getter protected Map<String, String> offset;

    protected long longOffsetValue(Map<String, ?> values, String key) {
        Object obj = values.get(key);
        if (obj == null) {
            return 0L;
        }
        if (obj instanceof Number) {
            return ((Number) obj).longValue();
        }
        try {
            return Long.parseLong(obj.toString());
        } catch (NumberFormatException e) {
            throw new ConnectException(
                    "Source offset '"
                            + key
                            + "' parameter value "
                            + obj
                            + " could not be converted to a long");
        }
    }

    public boolean isAtOrBefore(Offset that) {
        return this.compareTo(that) <= 0;
    }

    public boolean isBefore(Offset that) {
        return this.compareTo(that) < 0;
    }

    public boolean isAtOrAfter(Offset that) {
        return this.compareTo(that) >= 0;

View on GitHub (pinned to cf67b549a7)

Solutions

Check the offset map value for the given key; supply a numeric string (e.g. "position": "12345", not the filename)
Fix the startup offset config: the binlog filename goes in its own key; only the position is a long
If restored from a bad checkpoint, delete/redo the savepoint with a correctly formatted offset
Clear stale checkpoint state and restart the job from the corrected offset

Example fix

// before
// { "filename": "mysql-bin.000004", "position": "mysql-bin.000004" }
// after
// { "filename": "mysql-bin.000004", "position": "123456" }

Defensive patterns

Strategy: validation

Validate before calling

// Validate offset fields are numeric before starting from a specific offset:
String pos = offsetMap.get("position");
if (pos == null || !pos.matches("\\d+")) throw new IllegalArgumentException("position must be a long, got: " + pos);

Type guard

Long safeLong(Object v) { if (v instanceof Number) return ((Number) v).longValue(); try { return Long.parseLong(String.valueOf(v)); } catch (NumberFormatException e) { return null; } }

Try / catch

try { long p = offset.longOffsetValue("position"); }
catch (ConnectException e) { LOG.error("Bad offset value for {}: fix startup.offset config", e.getMessage()); throw e; }

Prevention

Never put the binlog filename into the position field
Validate startup.offset JSON types before job submission
Don't hand-edit checkpoint offset state

When it happens

Trigger: longOffsetValue(key) called with a map value like "mysql-bin.000004" (a non-numeric filename supplied where a numeric position was expected), null-adjacent garbage, or an offset restored from an incompatible checkpoint format.

Common situations: Users configuring startup.offset with the binlog FILE NAME in the position field instead of a number; checkpoint state written by a different connector version; hand-edited offset JSON with wrong types.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/c91226cb3b86f4b8. Report an issue: GitHub.