What causes "Unable to parse: ${resolvedModelPath}" in quarkusio/quarkus?

Run a clean build (mvn clean install) to remove stale/corrupt model JSON files.

quarkusio/quarkus · error · IllegalStateException

Unable to parse: ${resolvedModelPath}

Error message

Unable to parse: ${resolvedModelPath}

What it means

The Quarkus config documentation annotation processor (ConfigDocAnnotationProcessor) failed to read or parse a serialized config documentation model JSON file while merging per-extension models into one. mergeModel walks resolvedModelPath files, deserializes each into a ConfigRoot, and merges them; any IOException during parsing is wrapped in this IllegalStateException. It almost always means an existing quarkus-config-docs model JSON on the processing path is corrupt, stale, or unreadable.

Source

Thrown at core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/merger/ModelMerger.java:119

                        continue;
                    }

                    Map<ConfigRootKey, ConfigRoot> extensionConfigRoots = configRoots.computeIfAbsent(
                            normalizeExtension(configRoot.getExtension(), mergeCommonOrInternalExtensions),
                            e -> new TreeMap<>());

                    ConfigRootKey configRootKey = getConfigRootKey(javadocRepository, configRoot);
                    ConfigRoot existingConfigRoot = extensionConfigRoots.get(configRootKey);

                    if (existingConfigRoot == null) {
                        extensionConfigRoots.put(configRootKey, configRoot);
                    } else {
                        existingConfigRoot.merge(configRoot);
                    }
                }
            } catch (IOException e) {
                throw new IllegalStateException("Unable to parse: " + resolvedModelPath, e);
            }
        }

        // note that the configRoots are now sorted by extension name
        configRoots = retainBestExtensionKey(configRoots);

        for (Entry<Extension, Map<ConfigRootKey, ConfigRoot>> extensionConfigRootsEntry : configRoots.entrySet()) {
            List<ConfigSection> extensionGeneratedConfigSections = generatedConfigSections
                    .computeIfAbsent(extensionConfigRootsEntry.getKey(), e -> new ArrayList<>());

            for (ConfigRoot configRoot : extensionConfigRootsEntry.getValue().values()) {
                collectGeneratedConfigSections(extensionGeneratedConfigSections, configRoot);
            }
        }

        return new MergedModel(configRoots, configRootsInSpecificFile, generatedConfigSections);
    }

View on GitHub (pinned to e1c734241f)

Solutions

Run a clean build (mvn clean install) to remove stale/corrupt model JSON files.
Check the file at the path in the message: verify it is valid JSON, readable, and not truncated (0 bytes or cut off).
Delete the offending model JSON from the dependency jar or target directory and rebuild.
Ensure all modules are built with the same Quarkus version so the model format matches.
If caused by the processor itself failing to write then read its file, report with the full stack trace including the wrapped IOException.

Example fix

// before: stale corrupt model in target reused across builds
$ mvn install
IllegalStateException: Unable to parse: target/classes/quarkus-config-docs/model.json

// after: force regeneration of the model file
$ mvn clean install

Defensive patterns

Strategy: validation

Validate before calling

// before building, verify model files are valid JSON
Path model = Path.of("target/classes/quarkus-config-docs/model.json");
if (Files.exists(model)) {
    try (var in = Files.newInputStream(model)) {
        new ObjectMapper().readTree(in); // throws if corrupt
    }
}

Try / catch

try {
    mergeModel(...);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unable to parse:")) {
        Files.deleteIfExists(modelPath); // regenerate stale model
        mergeModel(...);
    } else throw e;
}

Prevention

Run mvn clean after Quarkus version upgrades to purge stale model JSON.
Never commit generated quarkus-config-docs model files to source control.
Keep all modules in a multi-module build on the same Quarkus version.
Check CI disk/permission health for target directories.

When it happens

Trigger: Running the annotation processor when the file at resolvedModelPath (an accumulated quarkus-config-docs model JSON from a previous round/dependency jar) exists but cannot be read or deserialized: truncated/corrupt JSON, unreadable file permissions, invalid encoding, or a model produced by an incompatible processor version.

Common situations: Incremental builds after a Quarkus upgrade left an old-format model JSON in target/ or a dependency jar; interrupted builds leaving partially written JSON; read-only or permission-denied output directories in CI; classpath pollution where a stale quarkus-config-docs model from another module is picked up.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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