deepseek-ai/deepseek-harness · error · AttachmentError

IMAGE_DIMENSION_TOO_LARGE

IMAGE_DIMENSION_TOO_LARGE

Error message

Image exceeds the configured per-side pixel limit.

What it means

Admission limit: after header parsing, detectImage refuses the image with IMAGE_DIMENSION_TOO_LARGE when either intrinsic side (perceived, EXIF-oriented) exceeds limits.maxDimension — the store default is 8192 (maxImageDimension). The cap applies to width and height independently; like the pixel cap it refuses rather than shrinks, since normalization runs only for admitted images.

Source

Thrown at packages/attachment/attachment-local/src/image.ts:122

  /** Per-side admission limit applied to width and height independently. */
  maxDimension?: number
}

/**
 * Fully decode a supported raster and return its intrinsic metadata.
 * @param data - complete encoded image bytes.
 * @param limits - intrinsic-dimension admission limits.
 * @returns verified format and dimensions.
 */
export async function detectImage(data: Uint8Array, limits?: DecodedImageLimits): Promise<DetectedImage> {
  try {
    const image = sharp(data, { failOn: 'error', limitInputPixels: false })
    const detected = await imageMetadata(image)
    if (limits?.maxPixels !== undefined && detected.width * detected.height > limits.maxPixels) {
      throw new AttachmentError('Image exceeds the configured decoded-pixel limit.', 'IMAGE_TOO_MANY_PIXELS')
    }
    if (limits?.maxDimension !== undefined && Math.max(detected.width, detected.height) > limits.maxDimension) {
      throw new AttachmentError('Image exceeds the configured per-side pixel limit.', 'IMAGE_DIMENSION_TOO_LARGE')
    }
    await image.raw().toBuffer()
    return detected
  } catch (error) {
    if (error instanceof AttachmentError) throw error
    throw new AttachmentError('Unsupported or malformed image data.', 'INVALID_IMAGE', { cause: error })
  }
}

View on GitHub (pinned to b150a551b8)

Solutions

  1. Downscale the long edge to the cap before submitting (fit: 'inside', withoutEnlargement: true keeps the aspect ratio).
  2. Raise maxImageDimension in the attachment-local config when long screenshots are expected workload.
  3. Check both caps: an image can pass the per-side test and still exceed the decoded-pixel product cap.

Example fix

// before
await store.saveImage({ data: tallScreenshot, mediaType: 'image/png' })

// after
const data = await sharp(tallScreenshot)
  .resize({ width: 8192, height: 8192, fit: 'inside', withoutEnlargement: true })
  .png().toBuffer()
await store.saveImage({ data, mediaType: 'image/png' })
Defensive patterns

Strategy: validation

Validate before calling

const { width, height } = await probeImage(bytes)
const cap = store.imageLimits.maxDimension
if (Math.max(width, height) > cap) {
  throw new Error(`long edge ${Math.max(width, height)}px exceeds ${cap}px`)
}

Type guard

import { isImageAdmissionError } from '@deepseek-ai/dsh-attachment'
const isDimensionTooLarge = (e: unknown): boolean =>
  isImageAdmissionError(e) && e.code === 'IMAGE_DIMENSION_TOO_LARGE'

Try / catch

try {
  await store.saveImage(input)
} catch (error) {
  if (isImageAdmissionError(error) && error.code === 'IMAGE_DIMENSION_TOO_LARGE') {
    // reject or shrink the long edge client-side; not a transient failure
  }
  throw error
}

Prevention

When it happens

Trigger: Submitting an image whose width or height exceeds maxDimension — tall full-page screenshots, skinny panoramas such as 1000x12000, rotated photos reporting a long side over 8192 — through saveImage/validateImage or detectImage with limits.

Common situations: Full-page web-capture screenshots with long scroll heights; banner strips; deployments that lowered maxImageDimension; ultra-tall mobile captures.

Related errors

AI-assisted analysis of deepseek-ai/deepseek-harness@b150a551b8 (2026-08-24). Data as JSON: /api/errors/d2f0b67f6c8d53e1. Report an issue: GitHub.