apache/seatunnel · critical · IllegalArgumentException

input must be defined.

Error message

input must be defined.

What it means

EdgeAgentConfigLoader.load builds a fully resolved agent configuration from the agent YAML. Before anything else it requires an 'input' section to be present; without an input source the agent has nothing to consume, so load throws IllegalArgumentException fail-fast.

Source

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

     *
     * <p>Entry point for {@code EdgeAgentRuntime.start()}. Resolves default input type {@code file}
     * and output type {@code console} when omitted.
     *
     * @param agentYamlPath path to the agent YAML file
     * @return immutable resolved snapshot for assembly and runtime
     * @throws Exception if the file is missing, YAML is invalid, or validation fails
     */
    public static EdgeAgentResolvedConfig load(Path agentYamlPath) throws Exception {
        return load(agentYamlPath, Paths.get("").toAbsolutePath());
    }

    public static EdgeAgentResolvedConfig load(Path agentYamlPath, Path installRoot)
            throws Exception {
        Path configPath = Objects.requireNonNull(agentYamlPath, "configPath");
        Path root = Objects.requireNonNull(installRoot, "installRoot").toAbsolutePath().normalize();
        AgentYamlConfig yaml = AgentYamlLoader.load(configPath);
        if (yaml.getInput() == null) {
            throw new IllegalArgumentException("input must be defined.");
        }

        EdgeAgentIdResolver.resolve(yaml, root);

        ReadonlyConfig agentConfig = AgentConfigBridge.agent(yaml.getAgent());
        ReadonlyConfig queueConfig = AgentConfigBridge.queue(yaml.getQueue());
        ReadonlyConfig retryConfig = AgentConfigBridge.retry(yaml.getRetry());
        AgentRuntimeConfig runtimeConfig =
                AgentRuntimeConfig.compose(
                        AgentSectionConfig.from(agentConfig),
                        QueueConfig.from(queueConfig),
                        AgentSchedulerConfig.from(agentConfig),
                        RetryConfig.from(retryConfig));

        ReadonlyConfig rawInputConfig = AgentConfigBridge.input(yaml.getInput());
        String inputType = EdgeAgentTypeResolver.resolveInputType(rawInputConfig);
        ReadonlyConfig inputConfig = EdgeAgentTypeResolver.withInputType(rawInputConfig, inputType);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add a valid 'input' section to the agent YAML.
2. Check the key spelling and top-level indentation ('input' must be top-level).
3. Validate the YAML parses as AgentYamlConfig with a non-null input before calling load.

Example fix

# before
agent:
  id: edge-agent-01
# after
input:
  plugin-name: MQTT
  ...
agent:
  id: edge-agent-01

AgentYamlConfig yaml = AgentYamlLoader.load(configPath);
if (yaml.getInput() == null) {
    throw new IllegalArgumentException("agent YAML must define a top-level 'input' section");
}

try { EdgeAgentResolvedConfig cfg = EdgeAgentConfigLoader.load(path, root); } catch (IllegalArgumentException e) { log.error("Agent config load failed: {}", e.getMessage()); }

When it happens

Trigger: Calling EdgeAgentConfigLoader.load(agentYamlPath, installRoot) where AgentYamlLoader parsed a YAML whose 'input' section is missing (yaml.getInput() == null).

Common situations: New agent YAML created with only agent/queue/retry sections; 'input' key misspelled (e.g. 'inputs' or 'source'); YAML indentation placing input under the wrong parent so it does not bind.

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}
• transport.aes-secret-key-base64 is required when transport.e

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