OpenAPITools/openapi-generator · error · RuntimeException

Exception while listing files in spec root directory: %s

Error message

Exception while listing files in spec root directory: %s

What it means

MergedSpecBuilder wraps an IOException from Files.walk while enumerating spec files under inputSpecRootDirectory during directory merge mode. The generator cannot start reading specs because the root directory does not exist, cannot be traversed, or an I/O error occurs mid-walk.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/config/MergedSpecBuilder.java:833

                adder.accept(name, value);
            }
        });
    }

    private List<String> getAllSpecFilesInDirectory() {
        Path rootDirectory = new File(inputSpecRootDirectory).toPath();
        try (Stream<Path> pathStream = Files.walk(rootDirectory)) {
            return pathStream
                    .filter(path -> !Files.isDirectory(path))
                    .filter(path -> {
                        String name = path.getFileName().toString().toLowerCase(Locale.ROOT);
                        return SPEC_EXTENSIONS.stream().anyMatch(name::endsWith);
                    })
                    .map(path -> rootDirectory.relativize(path).toString())
                    .sorted()
                    .collect(Collectors.toList());
        } catch (IOException e) {
            throw new RuntimeException("Exception while listing files in spec root directory: " + inputSpecRootDirectory, e);
        }
    }

    private void deleteMergedFileFromPreviousRun() {
        String targetDir = (outputDirectory != null) ? outputDirectory : inputSpecRootDirectory;
        try {
            Files.deleteIfExists(Paths.get(targetDir + File.separator + mergeFileName + ".json"));
        } catch (IOException ignored) {
        }
        try {
            Files.deleteIfExists(Paths.get(targetDir + File.separator + mergeFileName + ".yaml"));
        } catch (IOException ignored) {
        }
    }
}

View on GitHub (pinned to fcec517be3)

Solutions

1. Verify the spec root directory exists and the path is spelled correctly; prefer an absolute path in scripts and CI.
2. Run the generator from the directory the relative path was designed for, or fix the working directory configuration.
3. Ensure the executing user has read and traverse (execute) permission on the directory and its parents, especially in Docker.

Example fix

# before:
openapi-generator-cli generate -i ./openapi-specs -g java --additional-properties=mergeMode=deep
# after (absolute path, verified):
openapi-generator-cli generate -i /home/ci/pipeline/openapi-specs -g java --additional-properties=mergeMode=deep

// Pre-flight: verify the spec root is a readable directory before generating
import java.nio.file.*;

Path root = Paths.get(inputSpecRootDirectory);
if (!Files.isDirectory(root))
    throw new IllegalArgumentException("Spec root directory does not exist: " + root.toAbsolutePath());
if (!Files.isReadable(root))
    throw new IllegalArgumentException("Spec root directory is not readable: " + root.toAbsolutePath());

try {
    List<String> specs = readAllSpecFiles(); // wraps the Files.walk failure
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Exception while listing files in spec root directory")) {
        // log the absolute expected path and the CI user, then fail the build with a clear hint
        throw new BuildException("Check --input-spec path and permissions: " + e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: --input-spec (inputSpecRootDirectory) points at a path that does not exist (NoSuchFileException), a path with no traverse/read permission for the process, a broken symlink, or a filesystem error while streaming the directory tree.

Common situations: Relative path resolved from a different working directory in CI; typo in the --input-spec value; directory deleted between build steps; containerized run where the volume is not mounted at the expected path or the user lacks read permission.

Related errors

• Failed to generate .openapi-generator-ignore when the option
• Could not generate supporting file '{ignoreFileNameTarget}'
• Could not generate supporting file '{versionMetadata}'
• can't load template {name}
• inputSpecFiles list is empty — nothing to merge

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/e80c56abd05c51b6. Report an issue: GitHub.