ruvnet/ruflo · error

claim rejected ( )

Error message

claim rejected (${r.status}): ${claim.error ?? claim.message ?? 'unknown'}

What it means

Thrown when the federation relay's invite-claim endpoint (`POST /api/invites/claim`) responds with a non-2xx status. The join tool parses the JSON body for an `error` or `message` field and surfaces it with the HTTP status, since the relay rejected the invite redemption. It means the invite was refused server-side — e.g. the code is invalid, expired, already fully redeemed, or the NIP-98 auth did not verify.

Solutions

1. Read the embedded relay error (e.g. 'invite expired', 'max uses exceeded') and act on it: request a fresh invite via `x_federation_invite_mint` from an operator.
2. Verify the invite code matches /^v2\.[A-Za-z0-9._-]{8,}$/ and was copied in full (the client regex check catches format issues, but only the relay catches unknown/revoked codes).
3. Check system clock skew (NTP) if the status is 401, since NIP-98 auth windows reject badly skewed timestamps.
4. Confirm you are pointing at the relay that actually minted the code (relayHttp/relayWs options), not a different federation hub.
5. If the code was redeemed by the wrong key, have the operator mint a new single-use invite and retry with the intended key file.

Example fix

// before: retrying an exhausted invite blindly
await xFederationJoin({ code: oldCode });
// after: mint/obtain a fresh invite and validate format first
if (!/^v2\.[A-Za-z0-9._-]{8,}$/.test(newCode)) throw new Error('malformed invite code');
await xFederationJoin({ code: newCode });

const code = invite.code;
if (typeof code !== 'string' || !/^v2\.[A-Za-z0-9._-]{8,}$/.test(code)) {
  throw new Error('invite code must look like v2.<token>');
}
if (invite.expiresAt && Date.now() > new Date(invite.expiresAt).getTime()) {
  throw new Error('invite already expired locally; request a new one');
}

function isValidInviteCode(c: unknown): c is string {
  return typeof c === 'string' && /^v2\.[A-Za-z0-9._-]{8,}$/.test(c);
}

try {
  await xFederationJoin({ code });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('claim rejected')) {
    const status = e.message.match(/claim rejected \((\d+)\)/)?.[1];
    if (status === '401') console.error('NIP-98 auth failed — check clock skew');
    else console.error('invite refused by relay, request a fresh invite:', e.message);
  } else throw e;
}

When it happens

Trigger: Calling `x_federation_join` (or `ruflo federation join`) with an invite code the relay will not accept: an unknown/revoked code (404/403), an expired or use-exhausted code (409/410), a code already claimed by a different pubkey, or a NIP-98 Authorization header that fails signature/timestamp validation (401). The network request itself succeeded; the rejection is in the response status.

Common situations: Typing or truncating the invite code when copying it; joining with an invite whose 7-day TTL or maxUses (default 25) has lapsed; a replay attempt after the code was already redeemed; a system clock skewed far enough that the NIP-98 timestamp is rejected; the relay operator revoking the invite; hitting a different relay than the one that minted the code.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• no key held for — accept a grant first…
• no key held for — create it or accept a grant first
• channel must be pub: or prv:<16 hex>
• Concurrent write detected on aggregate
• Consensus is disabled

AI-assisted analysis of ruvnet/ruflo@2602b642d9 (2026-09-15). Data as JSON: /api/errors/b71c7dc0b6ec0a33. Report an issue: GitHub.

Appendix: source

Thrown at v3/@claude-flow/cli/src/mcp-tools/x-federation-join.ts:74

  description:
    'Join the open swarm federation with YOUR OWN key using an invite code: generates (or reuses) a local Nostr key at ~/.ruflo/nostr.key (0600), redeems the code with a NIP-98-signed claim directly against the relay, proves membership via NIP-42, and returns your pubkey. Use when you have been handed an invite code and want to participate as yourself. Asking an admin to `federation_admit` you instead is wrong for an open swarm because it centralizes onboarding and requires trusting a pubkey out of band; the invite claim binds membership to the key you hold. Never share the invite code publicly — it is a bearer secret.',
  inputSchema: { type: 'object', properties: {
    code: { type: 'string', description: 'Invite code (v2.…) received privately from a member/admin.' },
    relayHttp: { type: 'string', description: 'Relay HTTPS base for the claim; takes precedence over RUFLO_X_RELAY_HTTP.' },
    relayWs: { type: 'string', description: 'Relay wss URL for NIP-42; takes precedence over RUFLO_X_RELAY_WS.' },
    keyFile: { type: 'string', description: 'Key file path; takes precedence over RUFLO_NOSTR_KEY_FILE (default ~/.ruflo/nostr.key).' } }, required: ['code'] },
  handler: async (input) => {
    const i = input as { code: string; relayHttp?: string; relayWs?: string; keyFile?: string };
    const nt = await loadNostrTools();
    // Validate input before the optional-dependency check so a bad code fails fast and identically
    // whether or not nostr-tools is present.
    if (!/^v2\.[A-Za-z0-9._-]{8,}$/.test(i.code)) throw new Error('invite code must look like v2.<token>');
    if (!nt) return { degraded: true, reason: 'nostr-tools not installed', hint: 'npm i -g nostr-tools  (secp256k1 signing is not in node:crypto)' };
    const { sk, pubkey, created } = loadOrCreateKey(nt, i.keyFile);
    const url = `${HTTP_BASE(i.relayHttp)}/api/invites/claim`; const body = JSON.stringify({ code: i.code });
    const r = await fetch(url, { method: 'POST', headers: { Authorization: nip98Header(nt, sk, url, 'POST', body), 'Content-Type': 'application/json' }, body, signal: AbortSignal.timeout(20_000) });
    const claim = (await r.json().catch(() => ({}))) as { role?: string; error?: string; message?: string };
    if (!r.ok) throw new Error(`claim rejected (${r.status}): ${claim.error ?? claim.message ?? 'unknown'}`);
    const auth = await verifyMembership(nt, sk, RELAY_WS(i.relayWs));
    return { ok: auth.ok, pubkey, keyCreated: created, role: claim.role ?? 'member', membershipVerified: auth.ok, ...(auth.ok ? {} : { reason: auth.reason }),
      next: 'Publish kind-1 events tagged ["t","ruflo-swarm"] — or run `ruflo federation sync` to read the swarm.' };
  },
}];

View on GitHub (pinned to 2602b642d9)