Traditional Uploader Server-Side Notes & Requirements

In the FineUploader/server-examples repository you will find some code examples for different server platforms. If you can't find the one you need, please read the following on the server-side guidelines for handling multipart form requests and XHR upload requests in your language of choice.

Handling the upload requests

By default Fine Uploader will send the file in the body of a multipart encoded POST request. Each request contains a UUID parameter. By default, the name of this parameter is qquuid, but this is configurable in the request option section. This parameter value should be used to uniquely identify the file, and the association between this UUID and the file should be maintained sever-side if you want to handle DELETE requests, the resume feature, or chunking.


If chunking is enabled, the filename in the content-disposition header of the multipart file boundary will have a value of 'blob' so you will need to parse the value of the 'qqfilename' parameter in this case to determine the name of the associated file.


iOS devices use 'image.jpg' for all image file names. Ensure to save your files with the UUID somewhere in that file's path to ensure users are not overwriting each others' files.


Your server should return a valid JSON response to all requests. The content-type must be "text/plain" for older versions of Internet Explorer to work around an undesired behavior in the browser's handling of JSON responses.

Example values

  • {"success":true} when upload was successful.
  • {"success": false} if not successful, no specific reason.
  • {"error": "error message to display"} if not successful, with a specific reason.
  • {"success": false, "error": "error message to display", "preventRetry": true} to prevent Fine Uploader from making any further attempts to retry uploading the file
  • {"success": false, "error": "error message to display", "reset": true} to fail this attempt and restart with the first chunk on the next attempt. Only applies if chunking is enabled. Note that, if resume is also enabled, and this is the first chunk of a resume attempt, this will result in the upload starting with the first chunk immediately.
  • {"success":true, "newUuid": "abc-def-ghi"} When you would like to override the UUID for this file provided by Fine Uploader.


You can have additional custom properties in the response, but ensure that you include the 'success': true property for a successful response, or it will trigger the onError callback.

File Chunking/Partitioning

If you have file chunking turned on, each file will be split up into chunks that are sent, in order, in separate requests. Note that this feature is only supported in modern browsers.

On the server-side, you must acknowledge each chunked request just as you would a non-chunked request. If your response does not indicate success, Fine Uploader will declare the entire file a failure. If you have auto and/or manual retry enabled, Fine Uploader will retry beginning with the last failed chunk.

You must temporarily store each partition server-side and then concatenate all parts (to arrive at the complete file) after the last part is sent. See the paramNames chunking sub-option to see what specific parameters are sent by Fine Uploader along with each chunked request. These parameters will be necessary to ensure you properly parse each chunked request. You may order Fine Uploader to restart with the first chunk on a failed attempt by returning a reset property in your server response (with a value of true). This is only applicable if autoRetry or manualRetry is enabled.

You should make use of the UUID parameter, passed with each request, that uniquely identifies each file. This may make it easier for you to avoid collisions during accumulation of chunks between files with the same name. Furthermore, you should also set the chunking.success.endpoint option. Fine Uploader will send a POST to your endpoint when all chunks for a file have been successfully uploaded. This is the perfect opportunity to combine all chunks.

Resuming Uploads From A Previous Session

There isn't much you need to do, server-side, to support file resume, other than what has been discussed in the file chunking section above. You can determine if a resume has been ordered by looking for a "qqresume" param with a value of true. This parameter will be sent with the first request of the resume attempt.

It is important that you keep chunks around on the server until either the entire file has been uploaded and all chunks have been merged, or until the number of days specified in the recordsExpireIn property of the resume option have passed. If, for some reason, you receive a request that indicates a resume has been ordered, and one or more of the previously uploaded chunks is missing or invalid, you can return a valid JSON response containing a "reset" property with a value of "true". This will let Fine Uploader know that it should start the file upload from the first chunk instead of the last failed chunk.

Deleting Files

If you have enabled this feature, you will need to handle the corresponding DELETE or POST requests server-side. The method is configurable via the method property of the deleteFile option.

For DELETE requests, the UUID of the file to delete will be specified as the last element of the URI path. Any custom parameters specified will be added to the query string. For POST requests, the UUID is sent as a "qquuid" parameter, and a "_method" parameter is sent with a value of "DELETE". All POST request parameters are sent in the request payload.

Success of the request will depend solely on the response code. Acceptable response codes that indicate success are 200, 202, and 204 for DELETE requests and 200-204 for POST requests.

If you would like to enable the delete file feature for cross-origin environments in IE9 or older, you will need to set the allowXdr property of the cors client-side option and adjust your server-side code appropriately. Keep in mind that the Content-Type will be absent from the request header, and credentials (cookies) and non-simple headers cannot be sent.

CORS Support

As of version 3.3, Cross Origin Resource Sharing is supported. For more details on how this works, limitations, and how to properly configure your server, please see the blog post on CORS support, or the CORS feature page.

Providing your own UUID for files

If you would like to track files with your own generated UUID, you can return the new UUID for the file at any time in your server's response. If chunking is enabled, it generally would be most prudent to return this new UUID in the response to the first or last chunk. Once you return the new UUID in your response, Fine Uploader will update its client-side records and begin to use that UUID from that point forward. New UUIDs must be returned as the value of a newUuid property. See the values section above for an example.

Handling an Overridden Filename

This may happen, for example, if your user edits the file name. Simply look for a "qqfilename" parameter. If this exists in the request, be sure to use this when naming your file server-side.


If you would like to override the client-side generated preview (where supported) or provide a thumbnail for a non-previewable file that you have generated server-side, you can do so by providing an absolute or relative path (URL) to this thumbnail in your response to the upload request via a thumbnailUrl property in your JSON response. The URL may be cross-origin as well. See the previews/thumbnails feature page for more information on this feature.

POST when all chunks have successfully uploaded

You may specify a chunking.success.endpoint if you'd like your server to be called when all chunks have been successfully uploaded. See the section on the chunking success call for more details.