{"record":{"id":"5d613b4692d77b07","repo":"apache/seatunnel","slug":"agent-config-is-not-a-readable-file-yamlpath","errorCode":null,"errorMessage":"Agent config is not a readable file: ${yamlPath}","messagePattern":"Agent config is not a readable file: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/yaml/AgentYamlLoader.java","lineNumber":45,"sourceCode":"import java.nio.file.Path;\n\npublic class AgentYamlLoader {\n\n    private static final YAMLMapper YAML =\n            YAMLMapper.builder()\n                    .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)\n                    .visibility(PropertyAccessor.FIELD, JsonAutoDetect.Visibility.ANY)\n                    .visibility(PropertyAccessor.GETTER, JsonAutoDetect.Visibility.NONE)\n                    .visibility(PropertyAccessor.SETTER, JsonAutoDetect.Visibility.NONE)\n                    .build();\n\n    /**\n     * Reads YAML from {@code yamlPath} and applies {@code normalize}. Does not validate — callers\n     * must validate ReadonlyConfig slices after bridge conversion.\n     */\n    public static AgentYamlConfig load(Path yamlPath) throws IOException {\n        if (!Files.isRegularFile(yamlPath)) {\n            throw new IOException(\"Agent config is not a readable file: \" + yamlPath);\n        }\n        AgentYamlConfig cfg = YAML.readValue(yamlPath.toFile(), AgentYamlConfig.class);\n        normalize(cfg);\n        return cfg;\n    }\n\n    /** Normalizes legacy input shapes and applies null-safe defaults for optional sections. */\n    public static void normalize(AgentYamlConfig cfg) {\n        if (cfg == null) {\n            return;\n        }\n        cfg.ensureDefaults();\n        AgentYamlConfig.ReaderDefinition input = cfg.getInput();\n        if (input != null) {\n            input.normalizeLegacyPath();\n        }\n    }\n}","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/yaml/AgentYamlLoader.java#L27-L63","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the path exists and is a regular file (ls -l <path>); fix typos in the path argument.","Run the agent from the intended working directory or pass an absolute path to the YAML.","Check volume mounts/permissions if the config lives in a container or shared directory.","Create the config file from the shipped template if it was never generated."],"exampleFix":"// before\nagent.sh --config ./conf/agnet.yaml\n// after\nagent.sh --config /opt/agent/conf/agent.yaml","handlingStrategy":"validation","validationCode":"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); }","typeGuard":"boolean isReadableFile(java.nio.file.Path p) { return p != null && java.nio.file.Files.isRegularFile(p); }","tryCatchPattern":"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; }","preventionTips":["Pass absolute config paths in startup scripts.","Verify the file exists in CI before deploying.","Check container volume mounts for the config directory.","Standardize config location (e.g. $AGENT_HOME/conf/agent.yaml)."],"tags":["config","file-io","yaml","path"],"backgroundTag":"config-file-not-found","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}