ArchiveBox/ArchiveBox · error · HttpError

ArchiveResult chunk_index must be less than chunk_count

Error message

ArchiveResult chunk_index must be less than chunk_count

What it means

chunk_index is zero-based and must satisfy chunk_index < chunk_count. Sending an index beyond the declared total chunk count fails this check, guarding against off-by-one or duplicated final-chunk sends.

Source

Thrown at archivebox/api/v1_core.py:442

            "chunk_index",
        )
        chunk_count = _parse_archiveresult_upload_int(
            _get_archiveresult_upload_form_value(request, "chunk_count"),
            "chunk_count",
        )
        chunk_offset = _parse_archiveresult_upload_int(
            _get_archiveresult_upload_form_value(request, "chunk_offset"),
            "chunk_offset",
        )
        chunk_total_size = _parse_archiveresult_upload_int(
            _get_archiveresult_upload_form_value(request, "chunk_total_size"),
            "chunk_total_size",
        )

        if chunk_count < 1:
            raise HttpError(400, "ArchiveResult chunk_count must be at least 1")
        if chunk_index >= chunk_count:
            raise HttpError(400, "ArchiveResult chunk_index must be less than chunk_count")
        if chunk_total_size and chunk_offset > chunk_total_size:
            raise HttpError(400, "ArchiveResult chunk_offset cannot exceed chunk_total_size")

        if chunk_index == 0 and chunk_offset == 0 and storage.exists(relative_output_path):
            storage.delete(relative_output_path)

        current_size = storage.size(relative_output_path) if storage.exists(relative_output_path) else 0
        if current_size != chunk_offset:
            raise HttpError(
                409,
                f"ArchiveResult chunk offset mismatch for {relative_output_path}: expected {current_size}, got {chunk_offset}",
            )

        Path(storage.path(relative_output_path)).parent.mkdir(parents=True, exist_ok=True)
        with storage.open(relative_output_path, "ab") as destination:
            for chunk in uploaded_file.chunks():
                destination.write(chunk)

View on GitHub (pinned to 74564b2822)

Solutions

1. Ensure chunk_index ranges 0..chunk_count-1 and the same chunk_count is sent on every chunk request
2. Fix client loop bounds (i < chunkCount, zero-based)
3. Re-start the upload if the file changed and chunk_count was recalculated

Example fix

// before
for (let i = 0; i <= chunkCount; i++) await sendChunk(i)
// after
for (let i = 0; i < chunkCount; i++) await sendChunk(i, chunkCount)

if (!Number.isInteger(i) || i < 0 || i >= chunkCount) throw new Error(`chunk_index ${i} out of range 0..${chunkCount - 1}`);

const inRange = (i: number, n: number): boolean => Number.isInteger(i) && i >= 0 && i < n;

if (res.status === 400 && /chunk_index must be less than chunk_count/.test(await res.text())) throw new Error('Loop bounds or re-chunking desync — restart the upload with consistent chunk_count');

When it happens

Trigger: chunk_count=3 but chunk_index=3 (client looped one extra time); client recomputed chunk_count smaller mid-upload (file changed) while continuing with old indices; stale retry of a chunk after a corrected count.

Common situations: Race where the file was resized/re-chunked during upload; retry logic re-running the loop after the last chunk already succeeded; misreading zero-based indexing and using 1-based indices.

Related errors

• Exactly one ArchiveResult file chunk is required
• ArchiveResult chunk_count must be at least 1
• ArchiveResult chunk_offset cannot exceed chunk_total_size
• ArchiveResult {field_name} must be an integer
• ArchiveResult {field_name} must be non-negative

AI-assisted analysis of ArchiveBox/ArchiveBox@74564b2822 (2026-08-28). Data as JSON: /api/errors/91409ce70cf6ba5d. Report an issue: GitHub.