quarkusio/quarkus · error · IOException

Failed to create JBang install directory: ${dir}

Error message

Failed to create JBang install directory: ${dir}

What it means

JBangSupport.installJBang throws IOException 'Failed to create JBang install directory: <absolute path>' when the JBang installation directory (from getInstallationDir()) neither exists nor can be created via mkdirs(). This blocks downloading/unzipping JBang into place. The exception propagates as a wrapped RuntimeException to the caller of doEnsureJBangIsInstalledInternal.

Source

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

            dir = dir.map(Path::getParent);
        }
        return dir.map(d -> d.resolve(".jbang"))
                .orElseThrow(() -> new IllegalStateException("Failed to determine .jbang directory"));
    }

    private void installJBang() {
        try {
            String uri = "https://www.jbang.dev/releases/latest/download/jbang.zip";
            Path downloadDir = Files.createTempDirectory("jbang-download-");

            if (!downloadDir.toFile().exists() && !downloadDir.toFile().mkdirs()) {
                throw new IOException("Failed to create JBang download directory: " + downloadDir.toAbsolutePath().toString());
            }

            Path downloadFile = downloadDir.resolve("jbang.zip");
            Path installDir = getInstallationDir();
            if (!installDir.toFile().exists() && !installDir.toFile().mkdirs()) {
                throw new IOException("Failed to create JBang install directory: " + installDir.toAbsolutePath().toString());
            }
            HttpClient client = HttpClient.newBuilder().followRedirects(HttpClient.Redirect.ALWAYS).build();
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(new URI(uri))
                    .GET()
                    .build();
            HttpResponse<Path> response = client.send(request, BodyHandlers.ofFile(downloadFile));
            ZipUtils.unzip(downloadFile, downloadDir);
            ZipUtils.copyFromZip(downloadDir.resolve("jbang"), installDir);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Check permissions on the parent of the installation directory and create it manually: mkdir -p <installDir>
2. Ensure no regular file occupies the installation directory path (remove/rename it)
3. Override the JBang installation location to a writable path via the supported config/env and retry

Example fix

// before
ls -la ~/.quarkus  // jbang exists as a FILE

// after
mv ~/.quarkus/jbang ~/.quarkus/jbang.bak && mkdir -p ~/.quarkus/jbang

Path installDir = Paths.get(System.getProperty("user.home"), ".quarkus", "jbang");
File f = installDir.toFile();
if (f.exists() && !f.isDirectory())
    throw new IllegalStateException("Install path occupied by a file: " + installDir);
if (!f.exists() && !f.getParentFile().canWrite())
    throw new IllegalStateException("Cannot create install dir: " + installDir);

try {
    jbangSupport.ensureJBangIsInstalled();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("Failed to create JBang install directory")) {
        // mkdir -p the dir or remove the blocking file, then retry
    } else throw e;
}

When it happens

Trigger: Calling ensureJBangIsInstalled when the installation directory path cannot be created — parent path is a file, permissions deny mkdirs, or the filesystem is read-only.

Common situations: Read-only QUARKUS_USER_HOME or ~/.quarkus; a regular file exists at the installation dir path; enterprise-managed machines restricting writes to home; disk full.

Related errors

• Failed to restore the timestamp of the file:
• Failed to create ${classesDir}
• Failed to make the file executable: ${exe}
• failed to set file: ${script} executable. Protoc invocation
• Unable to determine if file '" + f + "' is a regular file

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