What causes "manual compaction could not produce a smaller summary" in deepseek-ai/deepseek-harness?

Inspect error.cause — it carries the original failure (code MAX_TOKENS, a provider error, or the shrink-check message) and selects the fix

deepseek-ai/deepseek-harness · error · ManualCompactionError

summary

summary

Error message

manual compaction could not produce a smaller summary

What it means

Thrown when a manual idle-session compaction (ctx.compaction.compactNow) fails while producing or validating its summary. The closing classifier puts every summary-stage failure that is not a changed-surface failure under code 'summary' and attaches the original error as `cause`. The conversation surface stays untouched; only the failed attempt (a compaction/start .. compaction/end pair carrying an error) remains in the session log.

Source

Thrown at packages/compaction/compaction-basic/src/region.ts:272

}

/** Classify one closed manual attempt without weakening cancellation precedence. */
function throwManualFailure(failure: TransactionFailure): never {
  if (failure.stage === 'commit') {
    throw new ManualCompactionError(
      'commit',
      'manual compaction did not commit cleanly',
      { cause: failure.error },
    )
  }
  if (failure.error instanceof SurfaceChangedError) {
    throw new ManualCompactionError(
      'changed',
      'the compacted history changed during manual compaction',
      { cause: failure.error },
    )
  }
  throw new ManualCompactionError(
    'summary',
    'manual compaction could not produce a smaller summary',
    { cause: failure.error },
  )
}

/**
 * Reject a durable unmatched compaction marker unless a later constructor-seed
 * boundary proves that its owner belongs to an earlier session lifecycle.
 * @param unmatchedCompactionStart - latest unmatched opening marker, if any.
 * @param latestEndSeedSeq - newest constructor-seed boundary, if any.
 * @param stage - operation label included in the busy diagnostic.
 */
function assertCompactionInactive(
  unmatchedCompactionStart: SessionEvent<'compaction/start'> | undefined,
  latestEndSeedSeq: number | undefined,
  stage: string,
): void {

View on GitHub (pinned to b150a551b8)

Solutions

Inspect error.cause — it carries the original failure (code MAX_TOKENS, a provider error, or the shrink-check message) and selects the fix
If the cause is MAX_TOKENS truncation, raise BasicCompactionConfig maxTokens above the 8192 default
If the cause is 'summary is not smaller than the shadowed content', widen the compacted range so the summary can be strictly smaller
For transient provider failures (rate limit, 5xx), retry compactNow later — the failed attempt left the surface intact
Route summarization to a concise instruction-following model via summarizationProvider/summarizationModel

Example fix

// before
try {
  await ctx.compaction.compactNow(agent, signal)
} catch (error) {
  throw error // opaque failure
}

// after
import { ManualCompactionError } from '@deepseek-ai/dsh-compaction'
try {
  await ctx.compaction.compactNow(agent, signal)
} catch (error) {
  if (error instanceof ManualCompactionError && error.code === 'summary') {
    report(`summarization failed: ${String(error.cause)}`)
    return
  }
  throw error
}

Defensive patterns

Strategy: try-catch

Type guard

import { ManualCompactionError } from '@deepseek-ai/dsh-compaction'
const isSummaryFailure = (error: unknown): error is ManualCompactionError =>
  error instanceof ManualCompactionError && error.code === 'summary'

Try / catch

try {
  await ctx.compaction.compactNow(agent, signal)
} catch (error) {
  if (isSummaryFailure(error)) {
    report('compaction summary failed', { cause: String(error.cause) })
    return // surface is intact; safe to stop or retry later
  }
  throw error
}

Prevention

Set maxTokens above the summarizer's realistic reasoning-plus-text budget
Configure summarizationProvider/summarizationModel to a concise text model instead of relying on the conversation route
Do not compact spans only a few nodes long — framing overhead can rival the content
Treat error.cause as the real diagnostic; the wrapper only classifies the stage

When it happens

Trigger: compactNow runs its auxiliary LLM summarization call and that call fails or its output is rejected: stream finish error/abort, MAX_TOKENS truncation ('summarization truncated at the token cap'), image output (UNSUPPORTED_CONTENT), no text content, or a framed summary that is not smaller than the shadowed span.

Common situations: maxTokens (default 8192) consumed by hidden reasoning tokens; provider outage or rate limit during the auxiliary call; compacting a span so short that checkpoint framing overhead rivals the content; a summarization model that restates the transcript near-verbatim.

Related errors

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