What causes "Failed to write collapsed spec {0}" in OpenAPITools/openapi-generator?

Pre-create the parent directory (mvn clean or any phase that creates target/) or point at a location that exists and is writable.

OpenAPITools/openapi-generator · error · MojoExecutionException

Failed to write collapsed spec {0}

Error message

Failed to write collapsed spec {0}

What it means

Thrown by CodeGenMojo when the <collapsedSpec> option is used: after resolving/merging the spec, the plugin serializes it to output/<collapsedSpec>.json|.yaml, and an IOException from mapper.writeValueAsString or FileUtils.writeStringToFile is wrapped in this MojoExecutionException whose message embeds the target path via MessageFormat. The writer does not create parent directories, so a missing output directory is the most common cause.

Source

Thrown at modules/openapi-generator-maven-plugin/src/main/java/org/openapitools/codegen/plugin/CodeGenMojo.java:1278

    private Path createCollapsedSpec() throws MojoExecutionException {
        // Merge the OpenAPI spec file.
        final var parseOptions = new ParseOptions();
        parseOptions.setResolve(true);
        final List<AuthorizationValue> authorizationValues = AuthParser.parse(this.auth);

        final var openApiMerged = new OpenAPIResolver(new OpenAPIV3Parser().readLocation(inputSpec, authorizationValues, parseOptions).getOpenAPI()).resolve();

        // Switch based on JSON or YAML.
        final var extension = inputSpec.toLowerCase(Locale.ROOT).endsWith(".json") ? ".json" : ".yaml";
        final var mapper = inputSpec.toLowerCase(Locale.ROOT).endsWith(".json") ? Json.mapper() : Yaml.mapper();

        // Write the merged spec to the output file.
        final var collapsedSpecPath = output.toPath().resolve(collapsedSpec + extension).toAbsolutePath();
        try {
            final var openApiString = mapper.writeValueAsString(openApiMerged);
            FileUtils.writeStringToFile(collapsedSpecPath.toFile(), openApiString, StandardCharsets.UTF_8);
        } catch (final IOException e) {
            throw new MojoExecutionException(new MessageFormat("Failed to write collapsed spec {0}", Locale.ROOT).format(collapsedSpecPath), e);
        }

        // Return the path to the collapsed spec file.
        return collapsedSpecPath;
    }
}

View on GitHub (pinned to fcec517be3)

Solutions

Pre-create the parent directory (mvn clean or any phase that creates target/) or point <output> at a location that exists and is writable.
Check the path in the error message: if a directory occupies the target file name, rename or remove it.
Free disk space / remove file locks (close IDE watchers, exclude the folder from antivirus scanning) and rerun.
If the directory is inherently read-only, change <output> to a writable path.

Defensive patterns

Strategy: validation

Validate before calling

# ensure the collapsed-spec parent directory exists before the mojo runs
mkdir -p target/generated-sources && mvn openapi-generator:generate

Prevention

Bind the generate goal to a phase after target/ is created (e.g. generate-sources), never to validate on a clean tree, when using collapsedSpec.
Keep the plugin <output> on a writable local filesystem, not a read-only container volume.
Exclude generated/collapsed spec output from IDE and antivirus file watchers to avoid locks.
If you do not need the flattened spec artifact, leave collapsedSpec unset.

When it happens

Trigger: Configuring <collapsedSpec>merged</collapsedSpec> in the generate goal while the plugin <output> directory does not exist yet or is not writable; the target path collides with an existing directory; disk full or filesystem lock (e.g. antivirus/IDE holding the file) during the write.

Common situations: First use of the collapsedSpec feature on a fresh checkout where target/ has not been created; read-only output locations in containers; Windows file locks from an IDE or indexer; very large merged specs exhausting disk space.

Related errors

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