Report errors during file upload to client API


Looking to see when an error occurred with my file upload. Is there a way to utilize a TUS hook to report error status to client API during file upload? How about when a file upload has been paused or abandoned?

Any insights into this is greatly appreciated.


Hello there, I assume you are using the tusd server. Let me know if that’s not the case.

Tusd provides a post-receive hook, which is executed regularly while the upload is running. It can be used to interrupt the upload in case of an error where the upload should not be continued. Have a look at the use case description at Customization via hooks | tusd documentation.

From my understanding, when tus invokes hooks like post-receive during an upload, it doesn’t distinguish between chunks sent during the initial upload or during a resumed upload. These hooks are triggered whenever data is received from the client, regardless of whether it’s part of an initial upload or a resumed one.

As a result, any logic implemented within the post-receive hook will apply equally to all chunks of data received during the upload process, regardless of whether it’s a new upload or a resumed one.

If I needed to differentiate between initial uploads and resumed uploads for some reason, would I need to implement additional logic or store metadata about the upload session to track its state?

The data provided to hooks also includes information from the original HTTP request that was sent to tusd. Based on the request method and headers you should be able to deduce if the current request is resuming an upload (PATCH request) or is for a new upload (POST request).

According to the tus protocol, PATCH is used for any chunk sent across, not just for resume.

Link: Resumable upload protocol 1.0.x |

Yes, that’s correct. Maybe it helps if you explain in more detail what you are trying to achieve. What is your exact definition or an “initial upload” versus a “resumed upload”?

Good question. To clarify, an “initial upload” refers to the first time a file or data is being uploaded to a server or system. It typically involves sending the entire file or data set in one go without any interruptions or previous attempts.

On the other hand, a “resumed upload” occurs when an upload process is interrupted or stopped for some reason, and then later resumed from where it left off. This could happen due to various reasons such as network issues, client-side interruptions, or intentional pausing of the upload process.

That’s a definition we can probably agree on. What is your question now that you need help with? :slight_smile:

The question that still remains is, how can we utilize a post-receive hook to report error status to client API during file upload given the fact that tus doesn’t distinguish between a chunk sent during a normal upload stream and a chunk sent after an upload has been resumed?

Why is it necessary to distinguish between these two case in your situation? It’s the first time I see someone asking for this.

There is an open PR at hooks: add pre-access blocking hook by sberthier · Pull Request #1077 · tus/tusd · GitHub for adding a hook for access control. It will be invoked before a request is being processed by tusd. Maybe that would be helpful for whatever you are trying to achieve.

The distinction is useful for data integrity. When an upload is resumed, we want to ensure that the data already uploaded is not overwritten or duplicated. Another plus for having this distinction is different error handling can be established for resumed uploads, abandoned uploads, or paused uploads.

Ensuring consistency and integrity of an upload resource is the task of the tus server, not the hooks, and is done by validating the Upload-Offset header. Hooks don’t need to be concerned with this because the managing entity of the upload resource (i.e. the tus server) prevents data loss through overwrites.

Thanks. Appreciate the insights!