{"record":{"id":"93ea99591524a1b3","repo":"alibaba/spring-ai-alibaba","slug":"agent-spec-directory-does-not-exist","errorCode":null,"errorMessage":"Agent spec directory does not exist: {}","messagePattern":"Agent spec directory does not exist: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/task/AgentSpecLoader.java","lineNumber":80,"sourceCode":"\n\t/**\n\t * Load agent specs from a directory (recursively scans for .md files).\n\t * @param directoryPath path to directory containing agent spec files\n\t * @return list of parsed specs\n\t */\n\tpublic static List<AgentSpec> loadFromDirectory(String directoryPath) throws IOException {\n\t\tif (!StringUtils.hasText(directoryPath)) {\n\t\t\treturn List.of();\n\t\t}\n\t\treturn loadFromDirectory(Paths.get(directoryPath));\n\t}\n\n\t/**\n\t * Load agent specs from a directory (recursively scans for .md files).\n\t */\n\tpublic static List<AgentSpec> loadFromDirectory(Path rootPath) throws IOException {\n\t\tif (rootPath == null || !Files.exists(rootPath)) {\n\t\t\tlogger.warn(\"Agent spec directory does not exist: {}\", rootPath);\n\t\t\treturn List.of();\n\t\t}\n\t\tif (!Files.isDirectory(rootPath)) {\n\t\t\tthrow new IOException(\"Path is not a directory: \" + rootPath);\n\t\t}\n\n\t\tList<AgentSpec> specs = new ArrayList<>();\n\t\ttry (Stream<Path> paths = Files.walk(rootPath)) {\n\t\t\tpaths.filter(Files::isRegularFile)\n\t\t\t\t\t.filter(p -> p.getFileName().toString().endsWith(\".md\"))\n\t\t\t\t\t.forEach(path -> {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tAgentSpec spec = loadFromFile(path);\n\t\t\t\t\t\t\tif (spec != null) {\n\t\t\t\t\t\t\t\tspecs.add(spec);\n\t\t\t\t\t\t\t\tlogger.debug(\"Loaded agent spec: {} from {}\", spec.name(), path);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/task/AgentSpecLoader.java#L62-L98","documentation":"AgentSpecLoader.loadFromDirectory was given a null or non-existent root path; it logs this warning and returns an empty list instead of throwing, so callers get zero agent specs loaded. This is a configuration problem: the directory you pointed the loader at is not present on disk.","triggerScenarios":"Calling loadFromDirectory(Path) with a path that was never created, was deleted, or is null; configuring an agent-spec directory property with a typo or a path valid on the dev machine but missing in the deployment container.","commonSituations":"Docker image not copying the agents directory, working-directory differences making a relative path resolve elsewhere, renamed/moved spec folder after an upgrade.","solutions":["Verify the path exists before loading: Files.exists(rootPath) and Files.isDirectory(rootPath).","Fix the configured directory path (check for typos and relative vs absolute resolution against the working directory).","Ensure the directory is packaged into the deployment artifact (e.g. add it to the container image or resources).","Create the directory with at least one .md spec file if it is meant to be populated."],"exampleFix":"// before\nPath dir = Path.of(\"agents\");\nvar specs = AgentSpecLoader.loadFromDirectory(dir);\n// after\nPath dir = Path.of(\"/app/config/agents\");\nif (!Files.isDirectory(dir)) throw new IllegalStateException(\"Agent spec dir missing: \" + dir);\nvar specs = AgentSpecLoader.loadFromDirectory(dir);","handlingStrategy":"validation","validationCode":"if (rootPath == null || !Files.isDirectory(rootPath)) throw new IllegalStateException(\"Agent spec directory missing: \" + rootPath);","typeGuard":null,"tryCatchPattern":"var specs = AgentSpecLoader.loadFromDirectory(dir); if (specs.isEmpty()) log.warn(\"No agent specs loaded from {}\", dir);","preventionTips":["Fail fast at startup when the configured spec directory is absent.","Use absolute paths or paths resolved from a known base directory.","Package the agents directory into container images and artifacts."],"tags":["filesystem","config","agent-spec"],"backgroundTag":"directory-not-found","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}