What causes "Failed to create catalog at: ${path}" in quarkusio/quarkus?

Check permissions on the parent directory of the catalog path and ensure the process user can write there

quarkusio/quarkus · error · IOException

Failed to create catalog at: ${path}

Error message

Failed to create catalog at: ${path}

What it means

CatalogService.writeCatalog wraps an IOException with message 'Failed to create catalog at: <absolute path>' when it cannot create the catalog file or its parent directories. The condition is: the file does not exist, parent mkdirs() failed, and createNewFile() also failed. The IOException is then rethrown as a RuntimeException, so callers see a wrapped unchecked exception.

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/cli/plugin/CatalogService.java:114

                    : objectMapper.readValue(path.toFile(), catalogType)).withCatalogLocation(path);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    /**
     * Write the catalog to the specified {@link Path}.
     * The method will create the directory structure if missing.
     *
     * @param catalog the catalog
     * @param path the path
     */
    public void writeCatalog(T catalog) {
        try {
            File catalogFile = catalog.getCatalogLocation().map(Path::toFile)
                    .orElseThrow(() -> new IllegalStateException("Don't know where to save catalog!"));
            if (!catalogFile.exists() && !catalogFile.getParentFile().mkdirs() && !catalogFile.createNewFile()) {
                throw new IOException("Failed to create catalog at: " + catalogFile.getAbsolutePath());
            }
            objectMapper.writeValue(catalogFile, catalog.refreshLastUpdate());
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }

    /**
     * Get the global catalog path that is under `.quarkus/cli/plugins/catalog.json` under the specified user home directory.
     * The specified directory is optional and the method will fallback to the `user.home` system property.
     * Using a different value if mostly needed for testing.
     *
     * @param userDir An optional user directory to use as a base path for the catalog lookup
     *
     * @return the catalog path wrapped as {@link Optional} or empty if the catalog does not exist.
     */
    public Path getUserCatalogPath(Optional<Path> userDir) {
        return relativePath.apply(userDir.orElse(USER_HOME));

View on GitHub (pinned to e1c734241f)

Solutions

Check permissions on the parent directory of the catalog path and ensure the process user can write there
Ensure the parent path is a directory, not an existing regular file (remove/rename the conflicting file)
Free disk space or point the catalog location to a writable path (configure catalog location explicitly)

Example fix

// before
ls -l ~/.quarkus  // 'config' exists as a FILE -> mkdirs fails

// after
mv ~/.quarkus/config ~/.quarkus/config.bak && mkdir ~/.quarkus/config

Defensive patterns

Strategy: try-catch

Validate before calling

File catalogFile = catalog.getCatalogLocation().map(Path::toFile).orElse(null);
if (catalogFile != null) {
    File parent = catalogFile.getParentFile();
    if (parent != null && !parent.isDirectory() && !(parent.exists() || parent.mkdirs()))
        throw new IllegalStateException("Cannot create catalog dir: " + parent);
    if (!catalogFile.canWrite() && catalogFile.exists())
        throw new IllegalStateException("Catalog file not writable: " + catalogFile);
}

Try / catch

try {
    catalogService.writeCatalog(catalog);
} catch (RuntimeException e) {
    if (e.getCause() instanceof IOException io && io.getMessage().startsWith("Failed to create catalog")) {
        // fix permissions / remove conflicting file, then retry once
    } else throw e;
}

Prevention

Verify the catalog directory is writable before invoking CLI commands
Ensure the catalog path's parent is a directory, not a regular file
Run in environments where the user home is writable (avoid read-only home mounts)

When it happens

Trigger: Calling writeCatalog when the catalog's parent directory cannot be created (permissions, path is a file, read-only filesystem) and the catalog file itself cannot be created.

Common situations: Read-only home directory or $QUARKUS_USER_HOME; a file exists where the catalog directory should be; disk full; sandboxed CLI environment blocking writes to the config dir.

Related errors

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