apache/seatunnel · critical · IllegalArgumentException

agent.id must be non-empty after resolution.

Error message

agent.id must be non-empty after resolution.

What it means

AgentSectionConfig parses the 'agent' section of the edge agent YAML into a typed config. After resolving AGENT_ID from the config, it rejects null or blank values because every agent instance requires a stable identity. This is a fail-fast guard during startup so the agent never runs without an id.

Source

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

import java.io.Serializable;
import java.util.Objects;

@Getter
public class AgentSectionConfig implements Serializable {

    private static final long serialVersionUID = 1L;

    private final String agentId;
    private final EdgeDeliveryGuarantee deliveryGuarantee;

    public AgentSectionConfig(ReadonlyConfig config) {
        Objects.requireNonNull(config, "config");
        ConfigValidator.of(config).validate(EdgeAgentRuntimeOptionRules.agentRule());

        String rawId = config.get(EdgeAgentRuntimeOptions.AGENT_ID);
        if (rawId == null || rawId.trim().isEmpty()) {
            throw new IllegalArgumentException("agent.id must be non-empty after resolution.");
        }
        this.agentId = rawId.trim();

        String rawDeliveryGuarantee = config.get(EdgeAgentRuntimeOptions.DELIVERY_GUARANTEE);
        EdgeDeliveryGuarantee.validateSupported(rawDeliveryGuarantee);
        this.deliveryGuarantee = EdgeDeliveryGuarantee.from(rawDeliveryGuarantee);
    }

    public static AgentSectionConfig from(ReadonlyConfig config) {
        return new AgentSectionConfig(config);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set a non-empty 'agent.id' in the agent YAML config.
2. Check EdgeAgentIdResolver output/id file to ensure identity resolution produced a value before this config is built.
3. Trim/verify the resolved id value (raw value must contain non-whitespace characters).

Example fix

# before
agent:
  id: ""
# after
agent:
  id: "edge-agent-01"

String id = config.get(EdgeAgentRuntimeOptions.AGENT_ID);
if (id == null || id.trim().isEmpty()) {
    throw new IllegalArgumentException("agent.id must be set before building AgentSectionConfig");
}

try { new AgentSectionConfig(config); } catch (IllegalArgumentException e) { log.error("Invalid agent config: {}", e.getMessage()); }

When it happens

Trigger: Constructing AgentSectionConfig with a ReadonlyConfig whose EdgeAgentRuntimeOptions.AGENT_ID is absent, null, or whitespace-only after resolution.

Common situations: User omits 'agent.id' in the agent YAML; id resolution (e.g. from an id file) failed upstream leaving an empty value; YAML has 'id: ""' or 'id:' with no value.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• input must be defined.
• input must be defined.
• transport.aes-secret-key-base64 is required when transport.e
• ${ClusterProperty.TCP_JOIN_PORT_TRY_COUNT} must be greater t
• Schema config can not be empty

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