{"record":{"id":"0ba362a79d330fdb","repo":"quarkusio/quarkus","slug":"failed-to-create-catalog-at-path","errorCode":null,"errorMessage":"Failed to create catalog at: ${path}","messagePattern":"Failed to create catalog at: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"independent-projects/tools/devtools-common/src/main/java/io/quarkus/cli/plugin/CatalogService.java","lineNumber":114,"sourceCode":"                    : objectMapper.readValue(path.toFile(), catalogType)).withCatalogLocation(path);\n        } catch (Exception e) {\n            throw new RuntimeException(e);\n        }\n    }\n\n    /**\n     * Write the catalog to the specified {@link Path}.\n     * The method will create the directory structure if missing.\n     *\n     * @param catalog the catalog\n     * @param path the path\n     */\n    public void writeCatalog(T catalog) {\n        try {\n            File catalogFile = catalog.getCatalogLocation().map(Path::toFile)\n                    .orElseThrow(() -> new IllegalStateException(\"Don't know where to save catalog!\"));\n            if (!catalogFile.exists() && !catalogFile.getParentFile().mkdirs() && !catalogFile.createNewFile()) {\n                throw new IOException(\"Failed to create catalog at: \" + catalogFile.getAbsolutePath());\n            }\n            objectMapper.writeValue(catalogFile, catalog.refreshLastUpdate());\n        } catch (IOException e) {\n            throw new RuntimeException(e);\n        }\n    }\n\n    /**\n     * Get the global catalog path that is under `.quarkus/cli/plugins/catalog.json` under the specified user home directory.\n     * The specified directory is optional and the method will fallback to the `user.home` system property.\n     * Using a different value if mostly needed for testing.\n     *\n     * @param userDir An optional user directory to use as a base path for the catalog lookup\n     *\n     * @return the catalog path wrapped as {@link Optional} or empty if the catalog does not exist.\n     */\n    public Path getUserCatalogPath(Optional<Path> userDir) {\n        return relativePath.apply(userDir.orElse(USER_HOME));","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/tools/devtools-common/src/main/java/io/quarkus/cli/plugin/CatalogService.java#L96-L132","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"// before\nls -l ~/.quarkus  // 'config' exists as a FILE -> mkdirs fails\n\n// after\nmv ~/.quarkus/config ~/.quarkus/config.bak && mkdir ~/.quarkus/config","handlingStrategy":"try-catch","validationCode":"File catalogFile = catalog.getCatalogLocation().map(Path::toFile).orElse(null);\nif (catalogFile != null) {\n    File parent = catalogFile.getParentFile();\n    if (parent != null && !parent.isDirectory() && !(parent.exists() || parent.mkdirs()))\n        throw new IllegalStateException(\"Cannot create catalog dir: \" + parent);\n    if (!catalogFile.canWrite() && catalogFile.exists())\n        throw new IllegalStateException(\"Catalog file not writable: \" + catalogFile);\n}","typeGuard":null,"tryCatchPattern":"try {\n    catalogService.writeCatalog(catalog);\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof IOException io && io.getMessage().startsWith(\"Failed to create catalog\")) {\n        // fix permissions / remove conflicting file, then retry once\n    } else throw e;\n}","preventionTips":["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)"],"tags":["filesystem","permissions","io"],"backgroundTag":"file-create-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}