quarkusio/quarkus · error · IllegalStateException

Quarkus extension registry configuration file ${configYaml}

Error message

Quarkus extension registry configuration file ${configYaml} specified by the system property ${CONFIG_FILE_PATH_PROPERTY} does not exist

What it means

locateConfigYaml() honors the system property quarkus.registries (CONFIG_FILE_PATH_PROPERTY) pointing at a custom registry config file; if the property is set but the referenced file does not exist on disk, it throws immediately instead of falling back to the default location. This fails fast so users know their explicit override is broken.

Source

Thrown at independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistriesConfigLocator.java:142

     * @return the registry client configuration file or null, if the file could not be found
     */
    public static Path locateConfigYaml() {
        return locateConfigYaml(null);
    }

    /**
     * Returns the registry client configuration file or null if the file could not be found.
     *
     * @param configYaml Path to a pre-specified config file (e.g. a command line argument)
     * @return the registry client configuration file or null if the file could not be found.
     */
    public static Path locateConfigYaml(Path configYaml) {
        if (configYaml == null) {
            final String prop = System.getProperty(CONFIG_FILE_PATH_PROPERTY);
            if (prop != null) {
                configYaml = Paths.get(prop);
                if (!Files.exists(configYaml)) {
                    throw new IllegalStateException("Quarkus extension registry configuration file " + configYaml
                            + " specified by the system property " + CONFIG_FILE_PATH_PROPERTY + " does not exist");
                }
                return configYaml;
            }

            configYaml = Paths.get("").normalize().toAbsolutePath().resolve(CONFIG_RELATIVE_PATH);
            if (Files.exists(configYaml)) {
                return configYaml;
            }

            configYaml = getDefaultConfigYamlLocation();
        }

        return Files.exists(configYaml) ? configYaml : null;
    }

    /**
     * Returns the default location of the registry client configuration file.

View on GitHub (pinned to e1c734241f)

Solutions

Check the resolved path printed in the message and create/copy the config YAML there (mkdir -p the parent dir if needed)
Fix the -Dquarkus.registries system property (or QUARKUS_LAUNCHER... whatever sets it) to the correct absolute path
Remove the system property if you intended to use the default ~/.quarkus/config.yaml location

Example fix

// before
-Dquarkus.registries=/etc/quarkus/registry-config.yml
// after (file actually exists)
-Dquarkus.registries=/etc/quarkus/registries.yaml

Defensive patterns

Strategy: validation

Validate before calling

String prop = System.getProperty("quarkus.registries");
if (prop != null && !Files.isRegularFile(Path.of(prop))) {
    throw new IllegalStateException("Registry config override does not exist: " + prop);
}

Try / catch

try {
    Path cfg = RegistriesConfigLocator.locateConfigYaml(override);
} catch (IllegalStateException e) {
    logger.error("Registry config missing: {}", e.getMessage());
}

Prevention

Use absolute paths in the quarkus.registries system property
In CI, assert the config file exists before launching Maven/Gradle Quarkus goals
In containers, verify the file is copied into the image at the referenced path

When it happens

Trigger: Running with -Dquarkus.registries=/path/to/config.yaml (or equivalent) where that path does not exist; a relative path resolved against the wrong working directory; the file was deleted/moved after being referenced.

Common situations: CI pipelines passing a config path from an env var that is unset or misspelled on the agent; Docker images where the config file was not copied to the expected path; switching working directories so a relative path no longer resolves.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

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