apache/seatunnel · error · IOException

Agent config is not a readable file: ${yamlPath}

Error message

Agent config is not a readable file: ${yamlPath}

What it means

AgentYamlLoader.load() requires the supplied path to be a regular readable file before parsing. If the path is missing, a directory, or otherwise not a regular file, it throws this IOException naming the path, without attempting YAML parsing.

Source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/yaml/AgentYamlLoader.java:45

import java.nio.file.Path;

public class AgentYamlLoader {

    private static final YAMLMapper YAML =
            YAMLMapper.builder()
                    .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
                    .visibility(PropertyAccessor.FIELD, JsonAutoDetect.Visibility.ANY)
                    .visibility(PropertyAccessor.GETTER, JsonAutoDetect.Visibility.NONE)
                    .visibility(PropertyAccessor.SETTER, JsonAutoDetect.Visibility.NONE)
                    .build();

    /**
     * Reads YAML from {@code yamlPath} and applies {@code normalize}. Does not validate — callers
     * must validate ReadonlyConfig slices after bridge conversion.
     */
    public static AgentYamlConfig load(Path yamlPath) throws IOException {
        if (!Files.isRegularFile(yamlPath)) {
            throw new IOException("Agent config is not a readable file: " + yamlPath);
        }
        AgentYamlConfig cfg = YAML.readValue(yamlPath.toFile(), AgentYamlConfig.class);
        normalize(cfg);
        return cfg;
    }

    /** Normalizes legacy input shapes and applies null-safe defaults for optional sections. */
    public static void normalize(AgentYamlConfig cfg) {
        if (cfg == null) {
            return;
        }
        cfg.ensureDefaults();
        AgentYamlConfig.ReaderDefinition input = cfg.getInput();
        if (input != null) {
            input.normalizeLegacyPath();
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the path exists and is a regular file (ls -l <path>); fix typos in the path argument.
2. Run the agent from the intended working directory or pass an absolute path to the YAML.
3. Check volume mounts/permissions if the config lives in a container or shared directory.
4. Create the config file from the shipped template if it was never generated.

Example fix

// before
agent.sh --config ./conf/agnet.yaml
// after
agent.sh --config /opt/agent/conf/agent.yaml

java.nio.file.Path p = java.nio.file.Paths.get(userPath); if (!java.nio.file.Files.isRegularFile(p)) { throw new IllegalArgumentException("Config path is not a file: " + p); }

boolean isReadableFile(java.nio.file.Path p) { return p != null && java.nio.file.Files.isRegularFile(p); }

try { cfg = AgentYamlLoader.load(path); } catch (IOException e) { if (e.getMessage().startsWith("Agent config is not a readable file")) { log.error("Fix --config path; not a regular file: {}", path); } throw e; }

When it happens

Trigger: Calling AgentYamlLoader.load(Path) with a path that does not exist, points to a directory, or is a special/non-regular file (device, fifo); typically from the agent startup command with a --config path argument.

Common situations: Typo in the config path on the command line; running the agent from a working directory different from where the YAML lives; config file deleted or not mounted in a container; passing a directory instead of a file.

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

• input must be defined.
• input must be defined.
• input.queue is no longer supported; configure top-level queu
• provided string configuration is null or empty! Please use a
• Invalid YAML configuration

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