apache/dolphinscheduler · error · IllegalArgumentException

Invalid key format

Error message

Invalid key format

What it means

DependentItem.fromKey parses a composite dependent-item key expected to have 4 dash-separated parts (definitionCode, depTaskCode, cycle, dateValue). Because task codes are unsigned longs, a negative dependency task code adds an extra empty part, giving 5 parts with an empty parts[1]. If the key splits into neither 4 parts nor that 5-part negative pattern, an IllegalArgumentException('Invalid key format') is thrown.

Source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-api/src/main/java/org/apache/dolphinscheduler/plugin/task/api/model/DependentItem.java:49

    private long depTaskCode;
    private String cycle;
    private String dateValue;
    private DependResult dependResult;
    private Boolean parameterPassing = false;

    public String getKey() {
        return String.format("%d-%d-%s-%s",
                getDefinitionCode(),
                getDepTaskCode(),
                getCycle(),
                getDateValue());
    }

    public DependentItem fromKey(String key) {
        String[] parts = key.split("-");
        boolean isNegativeDepTaskCode = parts.length == 5 && parts[1].isEmpty();
        if (parts.length != 4 && !isNegativeDepTaskCode) {
            throw new IllegalArgumentException("Invalid key format");
        }
        int offset = isNegativeDepTaskCode ? 1 : 0;
        setDefinitionCode(Long.parseLong(parts[0]));
        setDepTaskCode(Long.parseLong(isNegativeDepTaskCode ? "-" + parts[2] : parts[1]));
        setCycle(parts[2 + offset]);
        setDateValue(parts[3 + offset]);
        return this;
    }

}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Log the offending key and count its '-' separators; fix the producer so it emits exactly 4 segments (or 5 with empty second segment for negative codes).
2. Ensure the key is generated by DependentItem's own toKey/serialization rather than string concatenation elsewhere.
3. Check for negative task codes: they serialize with a leading '-' producing the 5-part form; only that exact shape is accepted.
4. Validate keys at API/DB ingestion time before they reach fromKey.
5. If parsing external input, catch IllegalArgumentException and reject the payload with a clear message.

Example fix

// before
String key = definitionCode + "-" + depTaskCode + "-" + cycle + "-" + dateValue; // breaks on negative depTaskCode? no—but manual joins break
// after
DependentItem item = new DependentItem().fromKey(item.toKey()); // always round-trip via the canonical serializer

static boolean isValidItemKey(String key) {
    String[] p = key.split("-", -1);
    return p.length == 4 || (p.length == 5 && p[1].isEmpty());
}

boolean isParsableKey(String key) { return key != null && isValidItemKey(key); }

try { item.fromKey(key); } catch (IllegalArgumentException e) { throw new BadRequestException("malformed dependent item key: " + key); }

When it happens

Trigger: Calling fromKey with a key that has fewer than 4 segments, more than 5, or 5 segments whose parts[1] is not empty (e.g. double dash in the wrong place, trailing dash, or a malformed code containing a dash). Any dependent-item key that was not produced by the matching toKey serialization.

Common situations: Manually constructed or hand-edited dependency keys in the DB/API payload; keys built by an older/newer version with a different separator; keys where a task code itself was corrupted; copy-paste dropping or duplicating a segment.

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

• data: %s should be a validate data string - yyyy-MM-dd HH:mm
• String json deserialization exception.
• Json deserialization exception.
• host:port '%s' illegal.
• The dependent task's project is not exist, dependentItem: ${

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/2f43295e3826ce00. Report an issue: GitHub.