Handoff not addressed to

Error message

Handoff not addressed to ${this.formatClaimant(claimant)}

What it means

ClaimService.acceptHandoff(issueId, claimant) found a 'handoff-pending' claim, but the claimant argument does not match the handoffTo target recorded by requestHandoff (isSameClaimant fails). Handoffs are addressed to a specific receiving agent, so only that agent can accept. The error names the claimant that tried to accept.

Solutions

Route the accept call to exactly the agent named in handoffTo (read it via getIssueStatus(issueId).handoffTo)
If the intended recipient changed, the owner must call requestHandoff again with the new target; the old pending handoff can be cleared via rejectHandoff by the current target
Keep agent identity stable across restarts so handoffTo comparisons succeed

Example fix

// before
await claims.acceptHandoff(issueId, anyWorker); // anyWorker !== handoffTo -> throws

// after
const claim = await claims.getIssueStatus(issueId);
if (claim?.status === 'handoff-pending' && isSame(claim.handoffTo, me)) {
  await claims.acceptHandoff(issueId, me);
}

Defensive patterns

Strategy: try-catch

Validate before calling

const claim = await claims.getIssueStatus(issueId);
const addressedToMe = claim?.status === 'handoff-pending' && !!claim.handoffTo && isSameClaimant(claim.handoffTo, me);
if (addressedToMe) await claims.acceptHandoff(issueId, me);

Try / catch

try {
  await claims.acceptHandoff(issueId, me);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Handoff not addressed to')) {
    // wrong recipient: ignore — the addressee will accept; or ask the owner to re-request to me
  } else throw e;
}

Prevention

Deliver handoff notifications only to the agent recorded in handoffTo
Compare against claim.handoffTo (from getIssueStatus) before accepting
Stabilize agent ids across restarts so the addressee identity still matches later

When it happens

Trigger: A different worker than the designated handoffTo calls acceptHandoff — e.g. the wrong agent picked up the notification, agent identity changed between request and accept, or accept code passes a default/service account Claimant instead of the intended recipient.

Common situations: Multiple workers subscribing to a shared handoff queue, restarted agents with regenerated ids, tests reusing one Claimant for both sides of the handoff.

Related errors

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/8560bfbb75284df4. Report an issue: GitHub.

Appendix: source

Thrown at v3/@claude-flow/cli/src/services/claim-service.ts:362

    await this.saveClaims();

    this.emitEvent({
      type: 'issue:handoff:requested',
      timestamp: new Date(),
      issueId,
      claimant: from,
      data: { to, reason },
    });
  }

  async acceptHandoff(issueId: string, claimant: Claimant): Promise<void> {
    const claim = this.claims.get(issueId);
    if (!claim || claim.status !== 'handoff-pending') {
      throw new Error(`No pending handoff for issue ${issueId}`);
    }

    if (!claim.handoffTo || !this.isSameClaimant(claim.handoffTo, claimant)) {
      throw new Error(`Handoff not addressed to ${this.formatClaimant(claimant)}`);
    }

    const previousClaimant = claim.claimant;
    claim.claimant = claimant;
    claim.status = 'active';
    claim.statusChangedAt = new Date();
    delete claim.handoffTo;
    delete claim.handoffReason;
    await this.saveClaims();

    this.emitEvent({
      type: 'issue:handoff:accepted',
      timestamp: new Date(),
      issueId,
      claimant,
      previousClaimant,
    });
  }

View on GitHub (pinned to fa13ee4ad6)