pbakaus/impeccable · error · Error

AI copy-edit batch did not return a valid completion payload

Error message

AI copy-edit batch did not return a valid completion payload. ${tail.trim()}

What it means

Thrown by runCopyEditBatchAgent() after codex or claude ran to completion but neither result.json nor the captured output parses into a valid batch result (parseCopyEditBatchResult returned null, i.e. status was not done/partial/error). The message appends the last ~1200 chars of agent.log (or output) so the underlying model/CLI failure is visible.

Source

Thrown at skill/scripts/live-copy-edit-agent.mjs:136

  const outDir = opts.outDir || fs.mkdtempSync(path.join(os.tmpdir(), 'impeccable-copy-batch-'));
  fs.mkdirSync(outDir, { recursive: true });
  const resultPath = path.join(outDir, 'result.json');
  const logPath = path.join(outDir, 'agent.log');

  if (provider === 'codex') {
    await runCodex(prompt, { cwd, env, resultPath, logPath, timeoutMs: opts.timeoutMs });
  } else if (provider === 'claude') {
    await runClaude(prompt, { cwd, env, resultPath, logPath, timeoutMs: opts.timeoutMs });
  } else {
    throw new Error(`Unsupported live copy-edit AI runner: ${provider}`);
  }

  const output = fs.existsSync(resultPath) ? fs.readFileSync(resultPath, 'utf-8') : '';
  const parsed = parseCopyEditBatchResult(output);
  if (parsed) return parsed;

  const tail = fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf-8').slice(-1200) : output.slice(-1200);
  throw new Error('AI copy-edit batch did not return a valid completion payload. ' + tail.trim());
}

export function runCopyEditPostApplyChecks({ cwd = process.cwd(), files = [] } = {}) {
  const failures = [];
  const warnings = [];
  const uniqueFiles = [...new Set((files || []).filter((file) => typeof file === 'string' && file.trim()))];
  for (const relativeFile of uniqueFiles) {
    const file = path.resolve(cwd, relativeFile);
    if (!isPathInsideOrEqual(cwd, file) || !fs.existsSync(file)) {
      warnings.push({ file: relativeFile, reason: 'file_missing_or_outside_cwd' });
      continue;
    }
    let content = '';
    try { content = fs.readFileSync(file, 'utf-8'); } catch (err) {
      failures.push({ file: relativeFile, reason: 'read_failed', message: err.message });
      continue;
    }
    const markerMatch = findLeftoverImpeccableMarker(content);

View on GitHub (pinned to d14711ae3d)

Solutions

  1. Read the tail included in the error — it usually contains the model/CLI reason (auth, rate limit, truncation).
  2. Check <tmpdir>/impeccable-copy-batch-*/agent.log for the full transcript.
  3. Retry with a stronger/larger model via IMPECCABLE_LIVE_COPY_AGENT_MODEL, or raise the timeout via opts.timeoutMs.
  4. If the CLI itself is misbehaving, run `claude setup-token`/`codex login` again or switch provider with IMPECCABLE_LIVE_COPY_AGENT.
Defensive patterns

Strategy: try-catch

Type guard

function isValidBatchResult(r) {
  return r && ['done', 'partial', 'error'].includes(r.status);
}

Try / catch

try {
  const result = await runCopyEditBatchAgent(batch, opts);
  return result;
} catch (err) {
  if (/did not return a valid completion payload/.test(err.message)) {
  // surface the agent.log tail, retry with a larger model/timeout, or fall back to mock
    console.error('Copy-edit payload invalid:', err.message);
    throw err;
  }
  throw err;
}

Prevention

When it happens

Trigger: The CLI exited cleanly but wrote no valid JSON; the model returned prose without the expected status field; a timeout/parse mismatch left result.json empty or malformed; the model was cut off mid-payload.

Common situations: Weak model that ignores the JSON schema; rate-limit/auth error mid-run that the CLI logged but did not surface as a non-zero exit; a prompt too large for the context window; an outdated CLI output format.

Related errors

AI-assisted analysis of pbakaus/impeccable@d14711ae3d (2026-08-13). Data as JSON: /api/errors/7046619b1b1a30a0. Report an issue: GitHub.