client-connection maxRequestBodyBytes (${String(maxRequestBo

Error message

client-connection maxRequestBodyBytes (${String(maxRequestBodyBytes)}) must be at least ${String(requiredImageBodyBytes)} for the configured aggregate image limit

What it means

At plugin apply, assertImageBodyCapacity checks that client-connection's maxRequestBodyBytes can carry one maximally image-laden request: the attachments service's aggregate maxMessageImageBytes inflates by 4/3 under base64, plus 1 MiB of JSON envelope headroom (REQUEST_ENVELOPE_HEADROOM_BYTES). A body cap under that floor fails the load immediately, so the first large image upload cannot die later as an opaque 413.

Source

Thrown at packages/client/connection/src/index.ts:39

} from './rpc.ts'
export { HostConnectionService } from './rpc-host.ts'

export { API_PATH, HOST_EVENTS_PATH, MUX_EVENTS_PATH } from './api-path.ts'

/** Stable Cordis plugin name. */
export const name = 'client-connection'

/** Headroom for RPC JSON fields around aggregate base64 image payloads. */
const REQUEST_ENVELOPE_HEADROOM_BYTES = 1024 * 1024

function assertImageBodyCapacity(ctx: Context, maxRequestBodyBytes: number): void {
  const attachments = ctx.get('attachments')
  if (attachments === undefined) return
  const requiredImageBodyBytes = Math.ceil(
    attachments.imageLimits.maxMessageImageBytes * 4 / 3,
  ) + REQUEST_ENVELOPE_HEADROOM_BYTES
  if (maxRequestBodyBytes < requiredImageBodyBytes) {
    throw new Error(
      `client-connection maxRequestBodyBytes (${String(maxRequestBodyBytes)}) must be at least `
      + `${String(requiredImageBodyBytes)} for the configured aggregate image limit`,
    )
  }
}

/** Services required before providing Connection; API Proxy is an optional `/api` fallback. */
export const inject = ['webServer']

/** Plugin config: the deployment's non-loopback serving authorities. */
export interface ConnectionConfig {
  /**
   * Authorities this deployment serves beyond loopback: exact `host:port`, or
   * port-less `host` matching any port. The /api trust fence refuses any
   * request whose Host is neither loopback nor listed here, so a
   * non-loopback (`0.0.0.0`) deployment must declare the names it is reached
   * by (the dsh CLI derives the machine's LAN IP literals itself). An entry
   * that is not a bare, canonical authority fails the plugin load.

View on GitHub (pinned to b150a551b8)

Solutions

Raise maxRequestBodyBytes to at least ceil(maxMessageImageBytes * 4/3) + 1048576 (the defaults satisfy this)
Or lower the attachments image limit so the existing body cap covers the base64-expanded worst case
Change both knobs in the same config review so the inequality always holds

Example fix

# before — body cap below the image budget
client-connection:
  maxRequestBodyBytes: 104857600        # 100 MiB
attachments:
  imageLimits:
    maxMessageImageBytes: 201326592     # 192 MiB → throws

# after
client-connection:
  maxRequestBodyBytes: 269484032        # ≥ 192 MiB × 4/3 + 1 MiB

Defensive patterns

Strategy: validation

Validate before calling

const REQUEST_ENVELOPE_HEADROOM_BYTES = 1024 * 1024
const required = Math.ceil(imageLimits.maxMessageImageBytes * 4 / 3) + REQUEST_ENVELOPE_HEADROOM_BYTES
if (config.maxRequestBodyBytes < required) {
  throw new Error(`raise maxRequestBodyBytes to at least ${required} for the configured image limit`)
}

Prevention

Treat the two limits as coupled: recompute the floor whenever either changes
Prefer the defaults unless a concrete constraint forces a change
Run a config preflight asserting the inequality before deploying

When it happens

Trigger: Loading client-connection with maxRequestBodyBytes set below ceil(maxMessageImageBytes * 4/3) + 1048576, or raising the attachments image limit without raising the body cap to match.

Common situations: Hardening passes shrink maxRequestBodyBytes and forget the image budget; a deployment raises maxMessageImageBytes to accept large screenshots and the old body cap now undercuts it.

Related errors

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