agalwood/Motrix · error · FsTaskError

plugin.fs.chunk_too_large

plugin.fs.chunk_too_large

Error message

plugin.fs.chunk_too_large: maxChunkSize ${maxChunkSize} > limit ${maxChunk}

What it means

Thrown by FsTaskReader.read(maxChunkSize) when the requested maxChunkSize exceeds the task's configured `maxReaderChunkBytes` (referenced as `maxChunk`, default is the module's DEFAULT_MAX_CHUNK, exercised as 16 MB in tests). The cap bounds per-read allocation. Code is `plugin.fs.chunk_too_large`. Checked synchronously at the top of read() before any I/O.

Source

Thrown at src/core/plugin/capabilities/fs-task.ts:191

        state.handle.close().catch(() => {})
      }
    }

    const ensureOpen = (): Promise<void> => {
      if (openPromise !== null) return openPromise
      openPromise = fs.open(filePath(), 'r').then((h) => {
        state.handle = h
      })
      return openPromise
    }

    // Start idle timer immediately
    resetIdle()

    const reader: FsTaskReader = {
      async read(maxChunkSize: number): Promise<Uint8Array | null> {
        if (maxChunkSize > maxChunk) {
          throw new FsTaskError(
            'plugin.fs.chunk_too_large',
            `plugin.fs.chunk_too_large: maxChunkSize ${maxChunkSize} > limit ${maxChunk}`
          )
        }

        // Auto-closed by idle timer
        if (state.closed) return null

        // Length cap: refuse to read past the requested length
        if (maxLength !== Infinity && bytesDelivered >= maxLength) return null

        await ensureOpen()
        if (state.closed) return null

        const remaining =
          maxLength === Infinity
            ? maxChunkSize
            : Math.min(maxChunkSize, maxLength - bytesDelivered)

View on GitHub (pinned to 1a708ee577)

Solutions

1. Clamp maxChunkSize to the task's limit before each read: `Math.min(reqSize, knownLimit)`.
2. Raise maxReaderChunkBytes in FsTask options if larger reads are needed and memory permits.
3. Discover the cap from the task config rather than hardcoding a number.
4. Loop reads with a fixed safe size (e.g. 1 MB) instead of one large request.

Example fix

// before
const buf = await reader.read(32 * 1024 * 1024) // > default 16 MB

// after
const CHUNK = 4 * 1024 * 1024 // safely under the 16 MB default
let buf: Uint8Array | null
while ((buf = await reader.read(CHUNK)) !== null) { /* handle */ }

function clampChunk(reqSize: number, limit: number): number {
  if (!Number.isFinite(reqSize) || reqSize <= 0) return Math.min(1 << 20, limit)
  return Math.min(reqSize, limit)
}

function isChunkTooLarge(e: unknown): boolean {
  return e instanceof Error && (e as FsTaskError).code === 'plugin.fs.chunk_too_large'
}

try {
  const buf = await reader.read(reqSize)
} catch (e) {
  if (isChunkTooLarge(e)) { /* retry with a smaller, safe chunk size */ }
  else throw e
}

When it happens

Trigger: Calling `reader.read(32 * 1024 * 1024)` on a task whose maxReaderChunkBytes is 16 MB; passing a user-controlled buffer size into read() without clamping; hardcoding a large chunk size that worked on a differently-configured task.

Common situations: Plugin tuned for a different default; passing through an HTTP range size unchanged; copying example code that assumed a higher cap.

Related errors

• plugin.fs.path_too_long
• plugin.fs.not_a_file
• plugin.fs.too_many_readers
• plugin.fs.rename_target_exists
• TaskNotFound

AI-assisted analysis of agalwood/Motrix@1a708ee577 (2026-08-12). Data as JSON: /api/errors/98d81f22eb15df68. Report an issue: GitHub.