sveltejs/kit · error · SvelteKitError

Could not deserialize binary form: gaps in file data

Error message

Could not deserialize binary form: gaps in file data

What it means

In the binary form payload, the declared file regions must exactly tile the files section: each file's end offset must not fall short of the next file's start offset. deserialize_binary_form throws 'gaps in file data' when there are unaccounted bytes between consecutive files, indicating a corrupted or inconsistent payload.

Source

Thrown at packages/kit/src/runtime/form-utils.js:332

					// Trick validators into thinking this is a normal File
					return File.prototype;
				}
			});
		}
	});

	// Sort file spans in increasing order primarily by offset
	// and secondarily by size (to allow 0-length files).
	file_spans.sort((a, b) => a.offset - b.offset || a.size - b.size);

	// Check that file spans do not overlap and there are no gaps between them.
	for (let i = 1; i < file_spans.length; i++) {
		const previous = file_spans[i - 1];
		const current = file_spans[i];

		const previous_end = previous.offset + previous.size;
		if (previous_end < current.offset) {
			throw deserialize_error('gaps in file data');
		}
		if (previous_end > current.offset) {
			throw deserialize_error('overlapping file data');
		}
	}

	// Read the request body asynchronously so it doesn't stall
	void (async () => {
		let has_more = true;
		while (has_more) {
			const chunk = await get_chunk(chunks.length);
			has_more = !!chunk;
		}
	})().catch(noop); // prevent unhandled rejection potentially crashing the process

	return { data, meta, form_data: null };
}
/**

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Verify Content-Length and that no intermediary truncates large uploads.
2. Keep client and server on the same @sveltejs/kit version.
3. Use native form POST or use:enhance so serialization is canonical.
4. Retry the upload; if reproducible, capture the raw body for diagnosis.

Example fix

// before: size not matching actual bytes
offsets: [0, 100], sizes: [50, 20] // gap between 50 and 100
// after: contiguous spans
offsets: [0, 50], sizes: [50, 20]

spans.sort((a, b) => a.offset - b.offset);
for (let i = 1; i < spans.length; i++) {
  if (spans[i - 1].offset + spans[i - 1].size < spans[i].offset) throw new Error('gap in file data');
}

try {
  await deserialize_binary_form(request);
} catch (e) {
  if (String(e.message).includes('gaps in file data')) {
    return new Response('Corrupted upload, please retry', { status: 400 });
  }
  throw e;
}

When it happens

Trigger: A SvelteKit action upload where file sizes/offsets in the offset table leave holes between files — truncated bodies, wrong 'size' values in metadata, hand-built payloads, or serializer version mismatch.

Common situations: Proxy buffering truncation on large multi-file uploads; clients editing payloads; version skew between client serializer and server deserializer; security probing of action endpoints.

Related errors

• Could not deserialize binary form: overlapping file data
• Could not deserialize binary form: file offset table too sho
• Could not deserialize binary form: invalid file offset table
• Could not deserialize binary form: invalid file metadata
• Could not deserialize binary form: duplicate file offset tab

AI-assisted analysis of sveltejs/kit@03f1687fe6 (2026-09-02). Data as JSON: /api/errors/0ec9a34438e878f8. Report an issue: GitHub.