apache/seatunnel · critical · IllegalArgumentException

input must be defined.

Error message

input must be defined.

What it means

EdgeAgentIdResolver.resolve assigns/resolves the agent identity from the YAML and an id file under the install root. It requires an 'input' section to exist before identity resolution and throws IllegalArgumentException when yaml.getInput() is null.

Source

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

import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Objects;
import java.util.Properties;
import java.util.UUID;

public class EdgeAgentIdResolver {

    public static final String ID_FILE_NAME = "edge-agent.id";
    static final String KEY_AGENT_ID = "agent.id";
    static final String KEY_INPUT_ID = "input.id";
    static final String KEY_OUTPUT_ID = "output.id";

    public static void resolve(AgentYamlConfig yaml, Path installRoot) throws IOException {
        Objects.requireNonNull(yaml, "yaml");
        Objects.requireNonNull(installRoot, "installRoot");
        if (yaml.getInput() == null) {
            throw new IllegalArgumentException("input must be defined.");
        }

        Path idFilePath = resolveIdFilePath(installRoot);
        Properties properties = loadOrCreate(idFilePath);

        resolveAgentId(yaml, properties);
        resolveInputId(yaml, properties);
        resolveOutputId(yaml, properties);

        syncResolvedIdsToProperties(yaml, properties);
        persist(idFilePath, properties);
    }

    private static void resolveAgentId(AgentYamlConfig yaml, Properties properties) {
        AgentYamlConfig.AgentSection agent = yaml.getAgent();
        if (agent == null) {
            yaml.setAgent(new AgentYamlConfig.AgentSection());
            agent = yaml.getAgent();

View on GitHub (pinned to cf67b549a7)

Solutions

1. Define a top-level 'input' section in the agent YAML.
2. Fix indentation/spelling so AgentYamlConfig.getInput() returns a value.
3. If resolving manually, check yaml.getInput() != null before calling resolve.

Example fix

// before
if (!yaml.containsKey("input")) { /* proceeds anyway */ }
// after
if (yaml.getInput() == null) {
    throw new IllegalArgumentException("input must be defined.");
}

if (yaml.getInput() == null) {
    throw new IllegalArgumentException("input must be defined before identity resolution");
}
EdgeAgentIdResolver.resolve(yaml, installRoot);

try { EdgeAgentIdResolver.resolve(yaml, root); } catch (IllegalArgumentException e) { log.error("Identity resolution failed: {}", e.getMessage()); }

When it happens

Trigger: Calling EdgeAgentIdResolver.resolve(yaml, installRoot) with an AgentYamlConfig whose input section is absent.

Common situations: Same as the loader guard: YAML missing the 'input' key, misspelled key, or input nested at the wrong indentation level so it binds to null.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• agent.id must be non-empty after resolution.
• input must be defined.
• input.queue is no longer supported; configure top-level queu
• Agent config is not a readable file: ${yamlPath}
• provided string configuration is null or empty! Please use a

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