django/django · error · NotImplementedError

subclasses of FileUploadHandler must provide a file_complete

Error message

subclasses of FileUploadHandler must provide a file_complete() method

What it means

FileUploadHandler.file_complete (uploadhandler.py:143) is an abstract method raising NotImplementedError. Subclasses must finalize the upload and return an UploadedFile object once all chunks are received. A handler without it cannot close out a file upload and raises when the parser signals completion.

Source

Thrown at django/core/files/uploadhandler.py:143

        self.content_type_extra = content_type_extra

    def receive_data_chunk(self, raw_data, start):
        """
        Receive data from the streamed upload parser. ``start`` is the position
        in the file of the chunk.
        """
        raise NotImplementedError(
            "subclasses of FileUploadHandler must provide a receive_data_chunk() method"
        )

    def file_complete(self, file_size):
        """
        Signal that a file has completed. File size corresponds to the actual
        size accumulated by all the chunks.

        Subclasses should return a valid ``UploadedFile`` object.
        """
        raise NotImplementedError(
            "subclasses of FileUploadHandler must provide a file_complete() method"
        )

    def upload_complete(self):
        """
        Signal that the upload is complete. Subclasses should perform cleanup
        that is necessary for this handler.
        """
        pass

    def upload_interrupted(self):
        """
        Signal that the upload was interrupted. Subclasses should perform
        cleanup that is necessary for this handler.
        """
        pass

View on GitHub (pinned to b5388a3a80)

Solutions

Implement file_complete(self, file_size) returning an UploadedFile instance.
Subclass TemporaryFileUploadHandler / MemoryFileUploadHandler to inherit a correct implementation.
If your handler only observes (e.g. progress), return None from file_complete to let later handlers own the file.

Example fix

// before
class MyHandler(FileUploadHandler):
    def receive_data_chunk(self, raw_data, start):
        self.buffer.write(raw_data)

// after
class MyHandler(FileUploadHandler):
    def receive_data_chunk(self, raw_data, start):
        self.buffer.write(raw_data)
    def file_complete(self, file_size):
        self.buffer.seek(0)
        return InMemoryUploadedFile(self.buffer, self.field_name, self.file_name, self.content_type, file_size, self.charset)

Defensive patterns

Strategy: type-guard

Validate before calling

from django.core.files.uploadhandler import FileUploadHandler

def handler_implements_complete(handler_cls):
    return handler_cls.file_complete is not FileUploadHandler.file_complete

Type guard

from django.core.files.uploadhandler import FileUploadHandler

def is_complete_upload_handler(handler_cls) -> bool:
    return (handler_cls.receive_data_chunk is not FileUploadHandler.receive_data_chunk
            and handler_cls.file_complete is not FileUploadHandler.file_complete)

Prevention

Ensure custom handlers return an UploadedFile from file_complete (or None to defer).
Cover both receive_data_chunk and file_complete in handler tests.
Prefer subclassing a concrete built-in handler.

When it happens

Trigger: A custom FileUploadHandler registered in FILE_UPLOAD_HANDLERS that omits file_complete; the upload pipeline reaches end-of-file and calls the missing method.

Common situations: Custom upload handler left incomplete; refactor that dropped the finalization method; misunderstanding the handler contract.

Related errors

AI-assisted analysis of django/django@b5388a3a80 (2026-08-10). Data as JSON: /api/errors/7c84fdbe9ef5e1c2. Report an issue: GitHub.