apache/seatunnel · error · FileNotFoundException

No agent.yaml found. Use --config /path/to/agent.yaml, set E

Error message

No agent.yaml found. Use --config /path/to/agent.yaml, set ENV_EDGE_AGENT_CONFIG, or place config/agent.yaml under the working directory.

What it means

EdgeAgentConfigLocator.resolve() searches --config, the ENV_EDGE_AGENT_CONFIG environment variable, and config/agent.yaml under the working directory; if none yields a regular file it throws FileNotFoundException telling the user all three resolution paths failed. This is the agent's startup configuration discovery failing.

Source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/command/EdgeAgentConfigLocator.java:51

    public static Path resolve(Path explicitConfigPath) throws IOException {
        if (explicitConfigPath != null) {
            return requireRegularFile(explicitConfigPath);
        }

        String env = System.getenv(EdgeAgentEnvConstants.ENV_EDGE_AGENT_CONFIG);
        if (env != null && !env.trim().isEmpty()) {
            return requireRegularFile(Paths.get(env.trim()));
        }

        Path cwd = Paths.get("").toAbsolutePath();
        for (String candidate : new String[] {"config/agent.yaml", "agent.yaml"}) {
            Path path = cwd.resolve(candidate).normalize();
            if (Files.isRegularFile(path)) {
                LOG.debug("Using agent config: {}", path);
                return path;
            }
        }
        throw new FileNotFoundException(
                "No agent.yaml found. Use --config /path/to/agent.yaml, set "
                        + EdgeAgentEnvConstants.ENV_EDGE_AGENT_CONFIG
                        + ", or place config/agent.yaml under the working directory.");
    }

    private static Path requireRegularFile(Path path) throws FileNotFoundException {
        Path normalized = path.toAbsolutePath().normalize();
        if (!Files.isRegularFile(normalized)) {
            throw new FileNotFoundException("Agent config file not found: " + normalized);
        }
        LOG.debug("Using agent config: {}", normalized);
        return normalized;
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Pass an explicit path: --config /absolute/path/to/agent.yaml
2. Set ENV_EDGE_AGENT_CONFIG to a valid agent.yaml path in the environment
3. Copy agent.yaml into ./config/agent.yaml relative to the working directory
4. Verify the resolved file exists and is a regular file (not a directory) with ls

Example fix

// before
sh bin/edge-agent.sh
// after
sh bin/edge-agent.sh --config /opt/agent/config/agent.yaml

Path cfg = Paths.get(configPath);
if (!Files.isRegularFile(cfg)) {
    throw new IllegalArgumentException("agent.yaml not found: " + cfg);
}

boolean isRegularFile(Path p) { return p != null && Files.isRegularFile(p.toAbsolutePath().normalize()); }

try {
    locator.resolve(args);
} catch (FileNotFoundException e) {
    LOG.error("Agent config missing: {}", e.getMessage());
    System.exit(2);
}

When it happens

Trigger: Starting the agent without --config, with ENV_EDGE_AGENT_CONFIG unset or pointing to a missing file, and no config/agent.yaml in the working directory.

Common situations: Running the starter from the wrong working directory; forgetting to set the env var in a container or systemd unit; a typo in the --config path; deploying without copying agent.yaml.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

• Agent config file not found: ${normalized}
• deploy mode not support : ${MODE}
• AmazonDocumentDB TLS CA bundle is not a readable file:
• Server property {} must contain at least one absolute execut
• python.script.path does not point to a readable file: {}

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