apache/seatunnel · error · IllegalArgumentException

Unsupported agent.delivery-guarantee: ${value}. Supported: B

Error message

Unsupported agent.delivery-guarantee: ${value}. Supported: BEST_EFFORT (aliases: best-effort, best_effort), NON (aliases: non, none).

What it means

EdgeDeliveryGuarantee.from normalizes the 'agent.delivery-guarantee' string to a supported enum value (BEST_EFFORT or NON, with case-insensitive aliases). If the raw value does not match any supported name or alias, it throws IllegalArgumentException listing the valid values.

Source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/config/EdgeDeliveryGuarantee.java:53

     * Returns the SPI factory identifier used to discover the matching {@link
     * org.apache.seatunnel.edge.agent.starter.wal.WalStoreFactory}.
     */
    public String storeFactoryId() {
        return storeFactoryId;
    }

    public static EdgeDeliveryGuarantee from(String value) {
        if (value == null || value.trim().isEmpty()) {
            return BEST_EFFORT;
        }
        String normalized = value.trim().replace('-', '_').toUpperCase(Locale.ROOT);
        if (Objects.equals(BEST_EFFORT.name(), normalized)) {
            return BEST_EFFORT;
        }
        if (Objects.equals(NON.name(), normalized) || Objects.equals("NONE", normalized)) {
            return NON;
        }
        throw new IllegalArgumentException(
                "Unsupported agent.delivery-guarantee: "
                        + value
                        + ". Supported: BEST_EFFORT (aliases: best-effort, best_effort),"
                        + " NON (aliases: non, none).");
    }

    public static void validateSupported(String value) {
        from(value);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Change agent.delivery-guarantee to BEST_EFFORT or NON (aliases accepted: best-effort, best_effort, non, none).
2. Check the YAML for typos or stray whitespace/quotes in the value.
3. Consult EdgeDeliveryGuarantee.validateSupported to validate the value before startup.

Example fix

# before
agent:
  delivery-guarantee: exactly-once
# after
agent:
  delivery-guarantee: BEST_EFFORT

String dg = config.get(EdgeAgentRuntimeOptions.DELIVERY_GUARANTEE);
Set<String> allowed = Set.of("BEST_EFFORT", "best-effort", "best_effort", "NON", "non", "none");
if (dg != null && !allowed.contains(dg.trim().toUpperCase())) {
    throw new IllegalArgumentException("Unsupported delivery-guarantee: " + dg);
}

try { EdgeDeliveryGuarantee.from(raw); } catch (IllegalArgumentException e) { log.error("delivery-guarantee rejected: {}", e.getMessage()); }

When it happens

Trigger: Calling EdgeDeliveryGuarantee.from(value) during AgentSectionConfig construction when agent.delivery-guarantee is any string other than BEST_EFFORT/best-effort/best_effort/NON/non/none (case-insensitive).

Common situations: Typo like 'at-least-once', 'exactly-once', or 'besteffort'; copied config from another system using different enum vocabulary; wrong casing assumptions.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown format type:
• Unknown ftp connection mode: ${mode}
• input.on-error must be "skip" or "fail".
• input.multiline.match must be "after" or "before".
• input.output-format.type must be "line" or "json".

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