What causes "Unable to deserialize config file: {configFile}" in OpenAPITools/openapi-generator?

Check the logged line above the exception — it carries the underlying Jackson/FileNotFound message; fix that (path, syntax, or structure).

OpenAPITools/openapi-generator · error · RuntimeException

Unable to deserialize config file: {configFile}

Error message

Unable to deserialize config file: {configFile}

What it means

CodegenConfigurator's config-file loader uses Jackson to read the file into DynamicSettings; any IOException (missing file, unreadable file, or YAML/JSON syntax error) is logged and rethrown as this RuntimeException. Note the original IOException is logged but not chained onto the thrown exception, so stack traces show only the wrapper — check the log line above the stack trace for the real cause. The config file is the JSON/YAML passed via -c/--config-file.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/config/CodegenConfigurator.java:203

        ObjectMapper mapper;

        if (FilenameUtils.isExtension(configFile.toLowerCase(Locale.ROOT), new String[]{"yml", "yaml"})) {
            mapper = Yaml.mapper().copy();
        } else {
            mapper = Json.mapper().copy();
        }

        if (modules != null && modules.length > 0) {
            mapper.registerModules(modules);
        }

        mapper.registerModule(new GuavaModule());

        try {
            return mapper.readValue(new File(configFile), DynamicSettings.class);
        } catch (IOException ex) {
            LOGGER.error(ex.getMessage());
            throw new RuntimeException("Unable to deserialize config file: " + configFile);
        }
    }

    public CodegenConfigurator addServerVariable(String key, String value) {
        this.serverVariables.put(key, value);
        generatorSettingsBuilder.withServerVariable(key, value);
        return this;
    }

    public CodegenConfigurator addAdditionalProperty(String key, Object value) {
        this.additionalProperties.put(key, value);
        generatorSettingsBuilder.withAdditionalProperty(key, value);
        return this;
    }

    public CodegenConfigurator addAdditionalReservedWordMapping(String key, String value) {
        this.reservedWordsMappings.put(key, value);
        generatorSettingsBuilder.withReservedWordMapping(key, value);

View on GitHub (pinned to fcec517be3)

Solutions

Check the logged line above the exception — it carries the underlying Jackson/FileNotFound message; fix that (path, syntax, or structure).
Validate the file parses: run it through `jq` (JSON) or `yamllint` (YAML) before generation.
Use an absolute path for -c, or confirm the working directory the CLI/maven plugin resolves relative paths from.
Compare your keys against a known-good config (generate with --dry-run or copy from the generator docs).

Example fix

# before: trailing comma
{ "groupId": "com.acme", }
# after
{ "groupId": "com.acme" }

Defensive patterns

Strategy: validation

Validate before calling

// Parse and structurally check the config before handing it to the generator
ObjectNode cfg = (ObjectNode) new ObjectMapper(new YAMLFactory()).readTree(new File(configFile));
for (String known : List.of("groupId", "artifactId", "artifactVersion", "java8", "library")) {
    // warn on unknown keys that look like typos of known ones
}
// readTree succeeding guarantees the syntax is valid before CodegenConfigurator runs

Try / catch

try { configurator.loadConfigFile(...); } catch (RuntimeException e) { log.error("config file {} invalid — see earlier log line for Jackson cause", path); fail build with clear message; }

Prevention

Validate config files with yamllint/jq in CI.
Use absolute paths for -c.
Never template placeholder syntax into config files; render them first.

When it happens

Trigger: -c config.json that doesn't exist (FileNotFoundException is an IOException); a JSON/YAML file with syntax errors; a config file whose structure does not match DynamicSettings binding; passing a spec file where the config file was expected.

Common situations: Relative config paths resolved from a different working directory in CI/maven plugins; YAML tabs or trailing commas; swapping -i (spec) and -c (config) arguments; template placeholders like ${...} left in the config from templated pipelines.

Related errors

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