affaan-m/ECC · error · Error

At least one --target is required for handoffs.

Error message

At least one --target is required for handoffs.

What it means

A handoff must declare at least one destination. runWriteCommand throws 'At least one --target is required for handoffs.' when options.targets is missing or an empty array for handoff commands. Targets tell the memory vault which agents/tasks the handoff is addressed to.

Solutions

1. Add at least one `--target <name>` flag to the handoff invocation (repeat the flag for multiple targets).
2. Verify the flag name/spelling matches what the parser expects (`--target`, repeated per recipient).
3. In scripts, guard the list: `[ ${#TARGETS[@]} -gt 0 ] || { echo 'need a target'; exit 1; }` before building the command.
4. If no recipient is known yet, defer the handoff or save as a regular note instead.

Example fix

// before
node scripts/memory.js handoff --title "ctx" --from claude --body-file ctx.md
// after
node scripts/memory.js handoff --title "ctx" --from claude --target codex --body-file ctx.md

if (command === 'handoff' && (!Array.isArray(opts.targets) || opts.targets.length === 0)) {
  throw new Error('handoff requires at least one --target.');
}

const hasTargets = (o) => Array.isArray(o?.targets) && o.targets.length > 0;

try {
  runWriteCommand(args);
} catch (err) {
  if (err.message === 'At least one --target is required for handoffs.') {
    console.error('Add one or more --target <name> flags to the handoff.');
  } else throw err;
}

When it happens

Trigger: Running `memory handoff` with --title and --from but no --target flags (or a wrapper collecting zero targets into an empty list). Raised in runWriteCommand after the --from check.

Common situations: Building the command dynamically from a targets list that ended up empty; typo-ing the flag (--targets vs repeated --target) so parsing yields no targets; template scripts where the recipient step was removed.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• --from is required for handoffs.
• An executable is required after --.
• An install config path is required
• await requires a file path
• Catalog show requires an install component ID

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/e0b2832cce0e5df2. Report an issue: GitHub.

Appendix: source

Thrown at scripts/memory.js:419

  }
}

function runInitCommand({ command, options, positionals, roots }) {
  requireNoPositionals(positionals, command);
  return printInit(
    initializeVault({ roots, scopes: options.scopes || undefined }),
    options.json
  );
}

function runWriteCommand({ command, options, positionals, roots }) {
  requireNoPositionals(positionals, command);
  if (!options.title) throw new Error('--title is required.');
  if (command === 'handoff' && !options.from) {
    throw new Error('--from is required for handoffs.');
  }
  if (command === 'handoff' && (!options.targets || options.targets.length === 0)) {
    throw new Error('At least one --target is required for handoffs.');
  }
  return printWrite(
    saveMemory(saveInput(options, command === 'handoff' ? 'handoff' : null), { roots }),
    options.json
  );
}

function runSearchCommand({ options, positionals, roots }) {
  const query = positionals.join(' ');
  return printSearch(query, searchMemories(query, {
    roots,
    scopes: options.scopes,
    kinds: options.kinds,
    targetHarness: options.targetHarness,
    limit: options.limit,
  }), options.json);
}

View on GitHub (pinned to 8321021c54)