quarkusio/quarkus · error · IllegalStateException

Unable to read the resolved model from: ${resolvedModelPath}

Error message

Unable to read the resolved model from: ${resolvedModelPath}

What it means

ConfigDocExtensionProcessor.finalizeProcessing, when debug is enabled, tries to read the resolved config model file it previously wrote to report it via the annotation processor Messager. If that file cannot be read (missing, locked, or IO error), it wraps the IOException in an IllegalStateException naming the path.

Source

Thrown at core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/ConfigDocExtensionProcessor.java:102

        ConfigResolver configResolver = new ConfigResolver(config, utils, configCollector);

        // the model is not written in the jar file
        JavadocElements javadocElements = configResolver.resolveJavadoc();
        if (!javadocElements.isEmpty()) {
            utils.filer().writeModel(Outputs.QUARKUS_CONFIG_DOC_JAVADOC, javadocElements);
        }

        ResolvedModel resolvedModel = configResolver.resolveModel();
        if (!resolvedModel.isEmpty()) {
            Path resolvedModelPath = utils.filer().writeModel(Outputs.QUARKUS_CONFIG_DOC_MODEL, resolvedModel);

            if (config.isDebug()) {
                try {
                    utils.processingEnv().getMessager().printMessage(Kind.NOTE,
                            "Resolved model:\n\n" + Files.readString(resolvedModelPath));
                } catch (IOException e) {
                    throw new IllegalStateException("Unable to read the resolved model from: " + resolvedModelPath, e);
                }
            }
        }

        // Generate files that will be stored in the jar and can be consumed freely.
        // We generate JSON files to avoid requiring an additional dependency to the YAML mapper
        if (!javadocElements.isEmpty()) {
            utils.filer().writeJson(Outputs.META_INF_QUARKUS_CONFIG_JAVADOC_JSON, javadocElements);
        }
        if (!resolvedModel.isEmpty()) {
            utils.filer().writeJson(Outputs.META_INF_QUARKUS_CONFIG_MODEL_JSON, resolvedModel);
        }
        if (!javadocElements.isEmpty() || !resolvedModel.isEmpty()) {
            utils.filer().write(Outputs.META_INF_QUARKUS_CONFIG_MODEL_VERSION, "1");
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Re-run the build (transient IO issue) ensuring target/ is not cleaned concurrently
Check file permissions on the resolved model path
Disable processor debug mode if you don't need the model dump
Report a processor bug if it reproduces consistently — the processor should tolerate its own debug read failing

Defensive patterns

Strategy: try-catch

Validate before calling

if (Files.notExists(resolvedModelPath) || !Files.isReadable(resolvedModelPath)) {
    log.warn("Resolved model not readable, skipping debug dump");
    return;
}

Try / catch

try {
    String model = Files.readString(resolvedModelPath);
} catch (IOException e) {
    // tolerate debug-dump failure; do not fail annotation processing
    processingEnv.getMessager().printMessage(Kind.WARNING, "Could not dump resolved model: " + e.getMessage());
}

Prevention

Don't clean target/ concurrently with annotation processing
Disable processor debug mode outside active debugging
Check disk permissions in CI containers
Report persistent reproduction as a processor bug

When it happens

Trigger: Running the annotation processor with debug enabled (quarkus-extension.debug or Options debug flag) and the resolved model file at resolvedModelPath is missing, deleted, unreadable (permissions), or the filesystem fails mid-processing.

Common situations: Debugging extension doc generation on a read-only or cleaned target directory; antivirus/OS locking files in target/; parallel builds racing to clean target while the processor reads the model.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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