HeyPuter/puter · error · Error

Failed to resolve prepared batch item for index ${index}

Error message

Failed to resolve prepared batch item for index ${index}

What it means

Thrown inside the JSON-body /fs/batchWrite path (non-multipart) when a prepared batch item is missing at a given array index during the concurrency-limited upload loop. Prepared via prepareBatchWrites from filteredRequests, so the items array should align 1:1 with filteredRequests. A missing item means the prepared batch has fewer entries than the request list — an internal invariant violation.

Source

Thrown at src/backend/controllers/fs/FSController.ts:884

                fileMetadata: requestBody.fileMetadata,
                thumbnailData: requestBody.thumbnailData,
                guiMetadata: requestBody.guiMetadata,
            })),
            storageAllowanceMax,
        );
        await this.services.fs.assertStorageAllowanceForPreparedBatch(
            preparedBatch,
            undefined,
            storageAllowanceMax,
        );

        const uploadResults = await runWithConcurrencyLimitSettled(
            filteredRequests,
            8,
            async (requestBody, index) => {
                const preparedItem = preparedBatch.items[index];
                if (!preparedItem) {
                    throw new Error(
                        `Failed to resolve prepared batch item for index ${index}`,
                    );
                }
                const uploadTracker = await this.#createUploadTracker(
                    userId,
                    preparedItem.objectKey,
                    preparedItem.normalizedInput.path,
                    preparedItem.normalizedInput.size,
                    requestBody.guiMetadata,
                );
                return this.services.fs.uploadPreparedBatchItem({
                    preparedBatch,
                    itemIndex: preparedItem.index,
                    fileContent: requestBody.fileContent,
                    encoding: requestBody.encoding,
                    uploadTracker,
                });
            },

View on GitHub (pinned to 908ec23eda)

Solutions

1. Treat as a server bug; report with the request body shape and item count.
2. Inspect FSService.prepareBatchWrites to confirm it returns items.length === input.length.
3. Retry once in case of transient state, then escalate if it reproduces.

async function robustJsonBatch(reqs, attempts = 2) {
  for (let i = 0; i < attempts; i++) {
    try { return await batchWrite(reqs); }
    catch (e) { if (/Failed to resolve prepared batch item/.test(e?.message ?? '') && i < attempts - 1) continue; throw e; }
  }
}

When it happens

Trigger: Not triggerable by a well-formed client request; preparedBatch.items should match filteredRequests.length. Would fire if prepareBatchWrites filters or reorders items differently from the controller's filteredRequests, or if a future edit changes the indexing contract. Thrown as a plain Error (not HttpError), so it surfaces as a 500.

Common situations: Encountered after edits to prepareBatchWrites that drop items or change array length. A mismatch between controller-side path filtering (#shouldIgnoreUploadPath) and service-side filtering.

Related errors

• conflict
• unauthorized
• not_found
• access_denied
• cannot_write_to_root

AI-assisted analysis of HeyPuter/puter@908ec23eda (2026-08-12). Data as JSON: /api/errors/98ab7cf9b45ed8f6. Report an issue: GitHub.