OpenAPITools/openapi-generator · error · RuntimeException

Could not generate supporting file '{versionMetadata}'

Error message

Could not generate supporting file '{versionMetadata}'

What it means

generateVersionMetadata (line 1973) writes <outputFolder>/.openapi-generator/<versionMetadataFilename> containing the generator's implementation version (used by later runs to detect version drift of generated code). When generateMetadata is true (default) and the write fails with IOException, it is wrapped with this message naming the target path. Like errors [5]/[7] the causes are filesystem ones, plus the specific case of a directory already existing where the VERSION file must be written.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultGenerator.java:1986

    /**
     * Generates a file at .openapi-generator/VERSION to track the version of user's latest run.
     *
     * @param files The list tracking generated files
     */
    private void generateVersionMetadata(List<File> files) {
        String versionMetadata = config.outputFolder() + File.separator + METADATA_DIR + File.separator + config.getVersionMetadataFilename();
        if (generateMetadata) {
            File versionMetadataFile = new File(versionMetadata);
            try {
                File written = this.templateProcessor.writeToFile(versionMetadata, (ImplementationVersion.read() + "\n").getBytes(StandardCharsets.UTF_8));
                if (written != null) {
                    files.add(versionMetadataFile);
                    if (config.isEnablePostProcessFile() && !dryRun) {
                        config.postProcessFile(written, "openapi-generator-version");
                    }
                }
            } catch (IOException e) {
                throw new RuntimeException("Could not generate supporting file '" + versionMetadata + "'", e);
            }
        } else {
            Path metadata = java.nio.file.Paths.get(versionMetadata);
            this.templateProcessor.skip(metadata, "Skipped by generateMetadata option supplied by user.");
        }
    }

    private Path absPath(File input) {
        // intentionally creates a new absolute path instance, disconnected from underlying FileSystem provider of File
        return java.nio.file.Paths.get(input.getAbsolutePath());
    }

    /**
     * Generates a file at .openapi-generator/FILES to track the files created by the user's latest run.
     * This is ideal for CI and regeneration of code without stale/unused files from older generations.
     *
     * @param files The list tracking generated files
     */

View on GitHub (pinned to fcec517be3)

Solutions

1. Check the printed path: verify its parent directories are writable and that no DIRECTORY occupies the VERSION file's path (rm -rf the stale .openapi-generator dir if corrupted).
2. Generate into a clean output directory to rule out leftovers from previous runs.
3. If you intentionally run with metadata disabled, confirm it is actually off - use DefaultGenerator.setGenerateMetadata(false) (also stops the default .openapi-generator-ignore of error [7]) rather than deleting the file afterwards.
4. Verify disk space and mount read/write flags in containerized environments.

Example fix

# before: stale/corrupt metadata dir blocks the write
# after: clean the metadata directory and regenerate
rm -rf out/.openapi-generator && openapi-generator generate -g java -i api.yaml -o out

// Pre-flight the metadata path: writable, and not blocked by a directory
Path out = Path.of(config.outputFolder());
Path version = out.resolve(".openapi-generator")
                .resolve(config.getVersionMetadataFilename());
Files.createDirectories(version.getParent());
if (Files.exists(version) && Files.isDirectory(version)) {
    throw new IllegalStateException("Directory occupies VERSION path: " + version);
}
if (!Files.isWritable(version.getParent())) {
    throw new IllegalStateException("Metadata dir not writable: " + version.getParent());
}

try {
    generator.opts(input).generate();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains(".openapi-generator")
            && e.getCause() instanceof java.io.IOException) {
        // clean out/.openapi-generator and retry once into a clean output dir
        throw new GenerationFailure("VERSION metadata unwritable", e.getCause());
    }
    throw e;
}

When it happens

Trigger: Output folder unwritable or absent; a directory named .openapi-generator/VERSION (or a conflicting path segment) already present from a corrupted previous run; read-only container mounts; antivirus/file-watcher locks on Windows; ENOSPC.

Common situations: CI workspaces with wrong ownership; Docker runs with read-only output volumes; stale output trees from interrupted earlier runs leaving half-created metadata paths; shared agents with disk quotas.

Related errors

• Failed to generate .openapi-generator-ignore when the option
• Could not generate supporting file '{ignoreFileNameTarget}'
• Failed to create the folder " + parent.getAbsolutePath() + "
• Could not generate model '{modelName}'
• Could not generate supporting file '{support}'

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