quarkusio/quarkus · error · RuntimeException

Form value is a string

Error message

Form value is a string

What it means

FormData.FileValue.getFileItem() throws when the form value is a plain string, not a file upload. Each multipart entry is either a string or a FileItemImpl; calling the file accessor on a string entry is invalid. A RuntimeException signals the mismatch.

Source

Thrown at independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/core/multipart/FormData.java:311

        }

        @Override
        public String getValue() {
            if (value == null) {
                throw new RuntimeException("Form value is a file");
            }
            return value;
        }

        @Override
        public String getCharset() {
            return charset;
        }

        @Override
        public FileItemImpl getFileItem() {
            if (fileItemImpl == null) {
                throw new RuntimeException("Form value is a string");
            }
            return fileItemImpl;
        }

        @Override
        public boolean isFileItem() {
            return fileItemImpl != null;
        }

        @Override
        public CaseInsensitiveMap<String> getHeaders() {
            return headers;
        }

        public String getFileName() {
            return fileName;
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Check value.isFileItem() before calling getFileItem() and fall back to getValue() for string entries.
2. Change the endpoint to accept String, or add a separate attribute, for the plain-text case.
3. Ensure the client actually sends the part as a file (multipart input with filename).
4. Handle both branches explicitly when reading FormData programmatically.

Example fix

// before
FileUpload file = (FileUpload) formData.get("note").getFileItem(); // may be a string
// after
var value = formData.get("note");
FileUpload file = value.isFileItem() ? value.getFileItem() : null;

if (!value.isFileItem()) { throw new BadRequestException("expected a file upload"); }

boolean isFile(FormData.FormValue v) { return v != null && v.isFileItem(); }

try { return value.getFileItem(); } catch (RuntimeException e) { if ("Form value is a string".equals(e.getMessage())) return null; throw e; }

When it happens

Trigger: Calling getFileItem() on a FormData attribute when the part was submitted as a simple form field (no filename), or declaring a FileUpload parameter for an attribute the client sends as plain text.

Common situations: Client posts a field without enctype=multipart or without a file input while the endpoint expects a file; differing clients hitting the same endpoint (one text, one file); code iterating form values assuming all are files.

Related errors

• Form value is a file
• Could not find MessageBodyWriter for ${entityClass} as ${med
• Media type '" + mediaType + "' in multipart request is not s
• Extra steps left over
• Unsupported value type: %s

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