ShareX Custom Uploader Form Data Failed: How to Fix Multipart Uploads

When a ShareX custom uploader reports that form data failed, the capture itself is often fine. The failure usually occurs because ShareX sends an upload request that does not match the body shape expected by the server. Common causes include an incorrect file form field name, using a raw request body instead of multipart form data, omitting a required parameter, manually setting an unsuitable Content-Type header, or placing JSON in the wrong part of the request.

This guide focuses specifically on request bodies and form fields. It does not cover authentication failures or response parsing except where an error message helps identify a malformed request. Work through the checks in order, test with a tiny image after each meaningful change, and stop as soon as the server accepts the upload.

1. Confirm the Symptom and Reproduce It With a Simple Test

Before editing the uploader, confirm that the problem is actually the outgoing upload request. Take a small screenshot, save it locally, and upload that file through the affected custom uploader. A tiny PNG or JPEG is ideal because it removes recording size, encoding time, and large-file limits from the test.

If ShareX captures the image successfully but the upload ends with an HTTP error, a server-generated validation message, or a complaint about a missing file or field, the custom uploader request is the likely cause. Messages such as “file is required,” “missing form field,” “unsupported media type,” “invalid multipart data,” or “invalid JSON” are especially relevant.

Do not begin by changing display, audio, OCR, hotkey, or image editor settings. Those settings affect how content is captured or processed, not how a completed file is arranged inside an HTTP request. If the image exists in the ShareX task history or on disk, capture-related settings have already done their job.

1.1 Separate Capture Problems From Upload Problems

Use the following observations to identify where the workflow breaks:

• If no image or recording is created, troubleshoot the capture workflow first.
• If the file is created but uploading fails, inspect the custom uploader request.
• If the server accepts the upload but ShareX cannot find the returned URL, investigate response parsing separately.
• If only large files fail, check server limits after confirming the multipart structure.

For this issue, success means the test file reaches the server and the server returns its normal successful response. Once that happens, stop changing request fields. Any remaining problem with copying or opening the returned URL belongs to a different stage.

1.2 Reproduce the Failure Consistently

Run the same tiny-file test two or three times without changing settings. A consistent error points toward a deterministic mismatch in the request. An intermittent timeout or connection reset may instead indicate a network or server availability problem.

Record the HTTP status code and exact response text if ShareX displays them. A status alone is not always decisive, but it provides context. For example, a server may use HTTP 400 or 422 when required form fields are missing, while HTTP 415 commonly indicates that the submitted media type is not supported. Servers can choose different status codes, so the response body and API documentation remain more important than assumptions based on the number.

2. Check the ShareX Settings Directly Related to This Problem

Open the custom uploader configuration and compare every request-related field with the receiving service's API documentation or a known working request. The comparison must be literal. Field names, capitalization, request method, body type, and parameter placement can all matter.

2.1 Verify the File Form Field Name

A multipart endpoint normally expects the uploaded file under a specific form field name. Common examples include file, image, upload, media, or attachment. These names are not interchangeable unless the server explicitly supports alternatives.

If the API documentation shows a request such as form-data: file=@screenshot.png, configure ShareX to send the file using the field name file. Do not use the filename, a local path, or a descriptive label such as screenshot unless that is the required field name.

A server saying that no file was provided even though ShareX selected a file is a strong sign that the file field name is wrong. Correct it, upload the tiny image again, and stop changing settings if the server accepts it.

2.2 Use Multipart Form Data When the Endpoint Requires It

Multipart form data packages a file and additional fields as separate parts of one request. This is different from sending the file bytes as the entire raw body. It is also different from sending one JSON document.

Choose multipart form data when the API documentation uses terms such as multipart/form-data, “form-data,” “file field,” or an example containing -F in a curl command. A curl example like -F "file=@image.png" -F "title=Example" describes two multipart fields: one file part and one text part.

Use a raw body only when the endpoint explicitly requires the file itself as the entire body. In that design, there is no surrounding named file field. Switching to a raw body merely because multipart failed usually makes the request less compatible with an endpoint expecting form fields.

2.3 Add Every Required Parameter in the Correct Location

Some upload APIs require additional fields alongside the file. Examples may include a destination folder, expiration period, upload type, privacy setting, title, or application-specific option. Add required form parameters with the exact names and allowed values shown in the API documentation.

Pay attention to where each parameter belongs:

• Multipart form field: Sent as another part beside the file.
• Query parameter: Added to the request URL.
• Header: Sent in the HTTP header collection.
• JSON property: Included inside a JSON body only when the endpoint accepts JSON.

A value in the wrong location is effectively missing from the server's perspective. For example, adding folder=images to the URL will not satisfy an API that requires a multipart field named folder.

2.4 Avoid Manually Forcing the Multipart Content Type

Multipart requests require a boundary value that separates each part. The HTTP client generating the multipart body normally creates the boundary and includes it in the Content-Type header. A manually entered header containing only multipart/form-data can conflict with the automatically generated header or omit the required boundary.

Unless the service documentation and ShareX configuration instructions explicitly say otherwise, remove a manually added multipart Content-Type header and allow ShareX to generate it with the body. Retain other headers that the endpoint genuinely requires, but do not duplicate headers without a clear reason.

Success after this fix means the server stops reporting an invalid or unparseable multipart body. If it then reports a specific missing field, the multipart envelope is probably readable and you should correct that field rather than continue changing headers.

3. Check Workflow and Destination Factors That Can Change the Request

Most Windows display, audio, and permission settings do not alter multipart form data. However, the selected ShareX destination and after-capture workflow determine which uploader runs and what type of file reaches it. Confirm these factors without broad system-wide troubleshooting.

3.1 Confirm the Intended Custom Uploader Is Active

ShareX can use different destinations for images, text, and files. Make sure the workflow is invoking the custom uploader you edited, not a different image host or file uploader. If several custom uploader configurations have similar names, temporarily rename the test configuration so it is easy to identify.

Also confirm that the file category matches the configured destination. A screenshot may use an image uploader, while a screen recording may be routed through a file uploader. Testing a tiny image is useful only if that image actually reaches the custom configuration under investigation.

3.2 Check Whether Earlier Workflow Steps Replace the File

Image effects, conversion, and recording workflows can change the final filename, extension, or media type. This rarely causes a missing multipart field, but it can matter when an endpoint accepts only certain formats. Confirm that the final file shown in task history has an allowed extension and opens correctly on the computer.

Clipboard content can also produce a different task than a file upload. If an endpoint requires a binary file part, test by uploading a saved image file rather than submitting clipboard text or a URL. Success means the server identifies the part as a file and processes its contents.

3.3 Rule Out Proxies or Security Tools Only When Evidence Points There

A proxy, VPN, filtering product, or security gateway can occasionally reject uploads or alter requests, but it is not the first suspect when the server explicitly says a named form field is missing. Investigate network middleware when requests time out, connections are reset, or an organization-branded gateway page replaces the API response.

If the server returns a clear validation error from the intended API, concentrate on body shape. That response proves the request reached an application capable of examining it.

4. Run a Clean Temporary Test With Minimal ShareX Settings

A minimal test helps expose duplicate fields, inherited headers, and optional parameters that make the request harder to understand. Create a temporary custom uploader rather than repeatedly changing a configuration you may need later.

1. Copy the exact upload endpoint and HTTP method from the current API documentation.
2. Select multipart form data if the documentation requires it.
3. Add only the file field using the documented field name.
4. Add only parameters explicitly marked as required.
5. Remove manually entered Content-Type headers unless the API requires a non-multipart type.
6. Leave response parsing rules aside until the server accepts the upload.
7. Upload a tiny PNG or JPEG and record the response.

If the minimal request succeeds, add optional fields back one at a time. Test after each addition. The first addition that recreates the failure identifies the conflicting field, invalid value, or incorrect placement.

4.1 Translate API Examples Into ShareX Fields

API documentation often provides a curl example rather than ShareX instructions. Read each component according to its role. The request URL belongs in the destination URL, the method belongs in the method setting, each -F entry usually represents a multipart field, and each -H entry represents a header.

Do not copy shell syntax, quotation marks, or the @ file marker as literal field values. Those symbols tell curl how to construct a request. ShareX has its own controls for selecting the uploaded file and assigning its form field name.

4.2 Recognize JSON Body Mistakes

JSON cannot directly contain raw binary file data in the same way as a multipart file part. Some APIs accept a JSON body containing base64-encoded content, but that is a distinct protocol and must be explicitly documented. Do not place a file placeholder inside JSON and expect a multipart endpoint to interpret it as an uploaded file.

Another design uses multipart form data with one file part and one text part whose value happens to be JSON. In that case, the JSON belongs under a specific multipart field name such as metadata. It is not the entire request body. Follow the API's exact example, including whether the metadata field requires a particular part content type.

If the API offers separate JSON and multipart endpoints, choose the multipart endpoint for an ordinary ShareX file upload unless you have a specific reason and supported configuration for JSON encoding.

5. Check Task History, Logs, and Server Error Messages

ShareX task history helps confirm which file was processed and whether the failure occurred during uploading. Review the failed task's details and any available error or response text. Preserve the exact message before rerunning tests because later attempts may return a different validation error.

5.1 Interpret Errors as Clues About Request Shape

• Missing file or required field: Check the file field name, body type, and parameter placement.
• Unsupported media type: Compare the request Content-Type with the endpoint's accepted body types.
• Malformed multipart body: Remove a manually forced Content-Type header and check for configuration conflicts.
• Invalid JSON: Confirm whether JSON is expected at all and whether it belongs in a multipart text field.
• Unexpected field: Remove undocumented fields or correct their names.
• File type not allowed: Test an accepted image format after confirming the server received the file part.

The most useful error is often the next one. Fixing the multipart envelope may reveal a missing parameter, and adding that parameter may reveal an invalid value. This progression indicates that the server is parsing more of the request each time.

5.2 Know When to Stop Changing ShareX

Stop editing the request once the server accepts the tiny test image and returns its normal successful payload. At that point, the file field, body format, and required parameters are working. If ShareX still does not copy a URL, open it, or display a thumbnail, treat that as a response parsing or after-upload workflow issue rather than a form-data failure.

If an identically structured request works in the service's official example but fails from ShareX, compare the actual method, URL, fields, and headers again. If they truly match, provide the service administrator with the timestamp, HTTP status, and response message so server-side logs can identify what was rejected.

6. Quick Fix Checklist

• Test with a tiny, valid PNG or JPEG.
• Confirm the capture succeeds before the upload begins.
• Verify that the intended custom uploader is selected.
• Match the HTTP method and endpoint exactly.
• Use multipart form data when the API requires form-data.
• Enter the exact documented file form field name.
• Add all required parameters in their documented locations.
• Remove an unnecessary manually entered multipart Content-Type header.
• Do not send a JSON body to a multipart-only endpoint.
• If JSON metadata is required, place it in the documented multipart field.
• Read the complete server response, not only the status code.
• Stop changing request settings as soon as the upload is accepted.

7. Frequently Asked Questions

7.1 Why Does the Server Say the File Is Missing When ShareX Selected It?

The server may be looking for a different form field name. A file uploaded under image will not satisfy an endpoint that only checks file. The same message can appear when ShareX sends a raw body while the endpoint expects a named multipart part.

7.2 Should I Add Content-Type multipart/form-data Manually?

Usually not. The multipart Content-Type needs a boundary matching the generated body. Letting the HTTP client create the header and boundary together avoids a common mismatch. Add or override it only when reliable documentation for the specific integration requires that configuration.

7.3 Can ShareX Send a File and JSON Together?

It can work when the API accepts multipart form data containing a file part and a separate text or JSON metadata part. The API must specify the metadata field name and expected format. That is different from sending the entire request as JSON.

7.4 Why Does a Curl Example Work but My ShareX Uploader Fails?

The requests may look similar while differing in one important detail. Compare the file field name, method, endpoint, query parameters, form fields, and headers. Do not paste curl-specific syntax such as @filename into ShareX as a literal value.

7.5 Could Windows Permissions Cause This Form-Data Error?

Permissions can prevent ShareX from reading or creating a file, but they normally do not cause an API to report a missing named form field after receiving the request. If the file exists and can be opened locally, focus first on multipart configuration and field placement.

7.6 What If the Tiny Image Works but a Recording Does Not?

The multipart structure is probably correct. Compare file size, extension, MIME type, upload duration, and the server's recording or file limits. Do not rebuild a working multipart configuration unless the server specifically reports a request-format problem.