quarkusio/quarkus · error · IllegalStateException

Unhandled type: " + rawType

Error message

Unhandled type: " + rawType

What it means

For a file-download response, the handler writes the body to a temp file and then must materialize it as the declared return type. Only java.io.File and java.nio.file.Path are supported; any other raw type declared by the client method while the response is classified as a file download triggers IllegalStateException.

Source

Thrown at independent-projects/resteasy-reactive/client/runtime/src/main/java/org/jboss/resteasy/reactive/client/handlers/ClientResponseCompleteRestHandler.java:135

                                fieldFiller.set(result, fieldValue);
                            }
                        } else if (httpData instanceof FileUpload fu) {
                            fieldFiller.set(result, new FileDownloadImpl(fu));
                        } else {
                            throw new IllegalArgumentException("Unsupported multipart message element type. " +
                                    "Expected FileAttribute or Attribute, got: " + httpData.getClass());
                        }
                    }
                } // close the else block for non-EntityPart multipart
            } else {
                Class<?> rawType = context.getResponseType().getRawType();
                if (context.isFileDownload()) {
                    if (File.class.equals(rawType)) {
                        builder.entity(new File(context.getTmpFilePath()));
                    } else if (Path.class.equals(rawType)) {
                        builder.entity(Paths.get(context.getTmpFilePath()));
                    } else {
                        throw new IllegalStateException("Unhandled type: " + rawType);
                    }
                    context.clearTmpFilePath();
                } else if (!void.class.equals(rawType)) {
                    Object entity = context.readEntity(entityStream,
                            context.getResponseType(),
                            responseContext.getMediaType(),
                            context.getMethodDeclaredAnnotationsSafe(),
                            // FIXME: we have strings, it wants objects, perhaps there's
                            // an Object->String conversion too many
                            (MultivaluedMap) responseContext.getHeaders());
                    if (entity != null) {
                        builder.entity(entity);
                    }
                    if (entity != null && !(entity instanceof InputStream)) {
                        entityStream.close();
                    }
                }
            }

View on GitHub (pinned to e1c734241f)

Solutions

1. Change the client method return type to java.io.File or java.nio.file.Path.
2. If you need other types, drop the file-download handling (adjust @Produces / annotations) and use the normal entity reader (e.g. byte[] with a matching media type).
3. Check the @ Produces media types on the client method so the response is not misclassified as a file download.
4. Return Response/FileDownload if you need streaming control.

Example fix

// before
@GET @Produces("application/octet-stream")
byte[] download();
// after
@GET @Produces("application/octet-stream")
Path download();

// File download methods must return File or Path
static void checkDownloadMethod(Method m, boolean isFileDownload) {
  if (isFileDownload && !(m.getReturnType() == File.class || m.getReturnType() == Path.class)) {
    throw new IllegalStateException("Download method must return File or Path, got " + m.getReturnType());
  }
}

When it happens

Trigger: A client method annotated to trigger file download (e.g. @Produces file media types with the download handling enabled) whose return type is neither File nor Path — e.g. returning byte[], String, or a custom type.

Common situations: Mixing response-type handling: declaring a custom DTO for an octet-stream response; switching return types during refactoring without changing the download handling expectation; upgrading Quarkus where file-download detection tightened.

Related errors

• Not supported return type for a multipart message, expected
• Failed to find multipart data for class " + responseClass +
• Unsupported multipart message element type. Expected FileAtt
• Unable to provide file for download
• returning size of a downloaded file is not supported

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