What causes "Unable to write the model to: ${yamlModelPath}" in quarkusio/quarkus?

Check the path in the message: ensure target/ is writable and has free disk space (df -h, ls -ld target).

quarkusio/quarkus · error · IllegalStateException

Unable to write the model to: ${yamlModelPath}

Error message

Unable to write the model to: ${yamlModelPath}

What it means

The processor serializes the generated config documentation model (a YAML file) under the module's target directory. FilerUtil.writeModel creates the parent directories and writes via Jackson's YAML mapper; any IOException during directory creation or file writing is wrapped in this IllegalStateException. The build fails because the docs model could not be persisted.

Source

Thrown at core/processor/src/main/java/io/quarkus/annotation/processor/util/FilerUtil.java:182

            processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Failed to write " + filePath + ": " + e);
            return;
        }
    }

    /**
     * The model files are written outside of target/classes as we don't want to include them in the jar.
     * <p>
     * They are not written by the annotation processor Filer API so we can use proper Paths.
     */
    public Path writeModel(String filePath, Object value) {
        Path yamlModelPath = getTargetPath().resolve(filePath);
        try {
            Files.createDirectories(yamlModelPath.getParent());
            JacksonMappers.yamlObjectWriter().writeValue(yamlModelPath.toFile(), value);

            return yamlModelPath;
        } catch (IOException e) {
            throw new IllegalStateException("Unable to write the model to: " + yamlModelPath, e);
        }
    }

    public Path getTargetPath() {
        try {
            FileObject dummyFile = processingEnv.getFiler().getResource(StandardLocation.CLASS_OUTPUT, "", "dummy");
            return Paths.get(dummyFile.toUri()).getParent().getParent();
        } catch (IOException e) {
            processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Unable to determine the path of target/" + e);
            throw new UncheckedIOException(e);
        }
    }

    public Optional<Path> getPomPath() {
        try {
            Path pomPath = Paths.get(processingEnv.getFiler().getResource(StandardLocation.CLASS_OUTPUT, "", "dummy").toUri())
                    .getParent().getParent().getParent().resolve("pom.xml");

View on GitHub (pinned to e1c734241f)

Solutions

Check the path in the message: ensure target/ is writable and has free disk space (df -h, ls -ld target).
Stop other builds and remove stale locks: kill parallel mvn processes and run ./mvnw clean, then rebuild.
Run the build as a user with write access to the project directory, or fix mount permissions.
Retry the build; if intermittent, avoid running multiple builds of the same module concurrently.

Example fix

// before (read-only output dir)
chmod 555 target && ./mvnw install
// after
chmod 755 target && ./mvnw clean install

Defensive patterns

Strategy: try-catch

Validate before calling

Path out = Paths.get("target", "quarkus-config-doc");
if (!Files.isWritable(out.getParent())
        || Files.getFileStore(out.getParent()).getTotalSpace()
               - Files.getFileStore(out.getParent()).getUsableSpace() < 0) {
    throw new IllegalStateException("target/ not writable");
}

Type guard

boolean canWriteModel(Path yamlModelPath) {
    Path parent = yamlModelPath.getParent();
    return parent != null && Files.isWritable(parent);
}

Try / catch

try {
    build();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unable to write the model to")) {
        cleanTargetAndRetry();
    } else throw e;
}

Prevention

Keep target/ directories writable by the build user.
Don't run multiple Maven builds of the same module concurrently.
Monitor disk space in CI runners.
Run ./mvnw clean if target files are stale or locked.

When it happens

Trigger: Writing the YAML model when the target directory cannot be created (permissions, read-only filesystem, disk full) or the output file cannot be opened/overwritten (locked by another process, path too long, permission denied).

Common situations: Read-only CI workspaces or NFS mounts; another build process holding target/quarkus-config-doc* files; disk quota exceeded; running builds concurrently on the same module.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/347183689f5efcc5. Report an issue: GitHub.