{"record":{"id":"19f5e23c8b124f84","repo":"quarkusio/quarkus","slug":"form-value-is-a-file","errorCode":null,"errorMessage":"Form value is a file","messagePattern":"Form value is a file","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/core/multipart/FormData.java","lineNumber":298,"sourceCode":"            this.fileItemImpl = new FileItemImpl(file);\n            this.headers = headers;\n            this.fileName = fileName;\n            this.value = null;\n            this.charset = null;\n        }\n\n        FormValueImpl(byte[] data, String fileName, CaseInsensitiveMap<String> headers) {\n            this.fileItemImpl = new FileItemImpl(data);\n            this.fileName = fileName;\n            this.headers = headers;\n            this.value = null;\n            this.charset = null;\n        }\n\n        @Override\n        public String getValue() {\n            if (value == null) {\n                throw new RuntimeException(\"Form value is a file\");\n            }\n            return value;\n        }\n\n        @Override\n        public String getCharset() {\n            return charset;\n        }\n\n        @Override\n        public FileItemImpl getFileItem() {\n            if (fileItemImpl == null) {\n                throw new RuntimeException(\"Form value is a string\");\n            }\n            return fileItemImpl;\n        }\n\n        @Override","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/core/multipart/FormData.java#L280-L316","documentation":"FormData.StringValue.getValue() throws when the form value was actually uploaded as a file, not a string. The internal form-data entry stores either a string or a FileItem; calling the string accessor on a file entry is a programming error by the parameter reader. The runtime signals this with a plain RuntimeException.","triggerScenarios":"Calling FormData attribute getValue() (or injecting a @RestForm String for an attribute) when the client sent a multipart file upload for that part, or the server-side @PartType maps it to FileUpload.","commonSituations":"A client changes the upload from a text field to a file input; the endpoint declares String parameter but the client posts multipart/form-data with a filename; shared code reading form values without checking isFileItem().","solutions":["Declare the endpoint parameter as FileUpload (io.quarkus.runtime.FileUpload) or Path instead of String for that @RestForm attribute.","Check isFileItem() before calling getValue() on the FormData value.","Have the client send the part as a plain field (no filename) if a string is expected.","Use getFileItem() on the value when isFileItem() returns true and read its content."],"exampleFix":"// before\n@RestForm String avatar; // breaks when a file is posted\n// after\n@RestForm FileUpload avatar;\n// then: avatar.uploadedFile() / java.nio.file.Files.readAllBytes(...)","handlingStrategy":"type-guard","validationCode":"if (value.isFileItem()) { throw new BadRequestException(\"expected a text field, got a file\"); }","typeGuard":"boolean isString(FormData.FormValue v) { return v != null && !v.isFileItem(); }","tryCatchPattern":"try { return value.getValue(); } catch (RuntimeException e) { if (\"Form value is a file\".equals(e.getMessage())) return null; throw e; }","preventionTips":["Match parameter types to what clients actually send","Check isFileItem() before getValue()","Keep @RestForm types consistent with the client form encoding","Add tests posting both field and file variants"],"tags":["multipart","form-data","rest"],"backgroundTag":"form-value-type-mismatch","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}