quarkusio/quarkus · error · IllegalArgumentException

Unable to provide file for download

Error message

Unable to provide file for download

What it means

FileDownloadImpl.filePath() wraps IOException in this IllegalArgumentException when it cannot materialize the downloaded multipart file on disk to return a Path. The download itself succeeded into a temp file, but reading/converting the underlying FileUpload to a java.nio.file.Path failed due to filesystem I/O problems.

Source

Thrown at independent-projects/resteasy-reactive/client/runtime/src/main/java/org/jboss/resteasy/reactive/client/impl/multipart/FileDownloadImpl.java:29

    // we're using netty's file upload to represent download too
    private final FileUpload file;

    public FileDownloadImpl(FileUpload httpData) {
        this.file = httpData;
    }

    @Override
    public String name() {
        return file.getName();
    }

    @Override
    public Path filePath() {
        try {
            return file == null ? null : file.getFile().toPath();
        } catch (IOException e) {
            throw new IllegalArgumentException("Unable to provide file for download", e);
        }
    }

    @Override
    public String fileName() {
        return file.getFilename();
    }

    @Override
    public long size() {
        throw new UnsupportedOperationException("returning size of a downloaded file is not supported");
    }

    @Override
    public String contentType() {
        return file.getContentType();
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Call filePath() promptly after receiving the response, before temp cleanup
2. Copy/move the file to persistent storage immediately and work from the copy
3. Check disk space and permissions on the temp directory (java.io.tmpdir)
4. Inspect the wrapped IOException cause for the real filesystem error

Example fix

// before
Path p = download.filePath(); // may throw IllegalArgumentException on I/O failure
// after
Path p;
try {
    p = download.filePath();
    Files.move(p, persistentPath, StandardCopyOption.REPLACE_EXISTING);
} catch (IllegalArgumentException | IOException e) {
    throw new IOException("Failed to persist downloaded file", e);
}

Path tmpDir = Path.of(System.getProperty("java.io.tmpdir"));
if (!Files.isWritable(tmpDir)) throw new IllegalStateException("Temp dir not writable");

try {
    Path p = download.filePath();
    Files.copy(p, dest, StandardCopyOption.REPLACE_EXISTING);
} catch (IllegalArgumentException e) {
    throw new IOException("Downloaded file unavailable on disk: " + e.getCause(), e);
}

When it happens

Trigger: Calling filePath() on a MultipartFormDataDownload/FileDownload when the backing temp file has been deleted, disk is full, permissions deny access, or the file was moved before filePath() was invoked.

Common situations: Temp directories cleaned up aggressively (systemd-tmpfiles, containers with tmpfs), read-only or full disks, concurrent requests where response files are accessed after cleanup, long-lived references to downloads whose temp files expired.

Related errors

• returning size of a downloaded file is not supported
• PartType annotation is only supported on fields and (setter/
• Primitive types are not supported for multipart response map
• Unsupported field type for multipart response mapping: " + t
• multipart responses can only be mapped to non-generic classe

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