What causes "Invalid target format: ${target}. Use agent: or human: " in ruvnet/ruflo?

Re-run the command with an explicit prefix, e.g. --target agent:coder-1 or --target human:alice

Invalid target format

Error message

Invalid target format: ${target}. Use agent:<id> or human:<id>

What it means

Thrown by parseTarget in the @claude-flow/claims CLI when a claimant target string cannot be parsed as 'agent:<id>' or 'human:<id>'. The string is split on ':' and both halves must be present with type exactly 'agent' or 'human'; anything else (missing colon, unknown prefix, empty id) is rejected before any claim operation runs.

Solutions

Re-run the command with an explicit prefix, e.g. --target agent:coder-1 or --target human:alice
Check the claimant's registered type via the claims list/users command and use the matching prefix
Fix the script that assembles the target string to always emit `${type}:${id}` with type validated against ['agent','human']

Example fix

# before
claims grant --target coder-1 --capability deploy
# throws: Invalid target format: coder-1. Use agent:<id> or human:<id>

# after
claims grant --target agent:coder-1 --capability deploy

Defensive patterns

Strategy: type-guard

Validate before calling

const TARGET_RE = /^(agent|human):(.+)$/;
if (!TARGET_RE.test(target)) {
  throw new Error(`target must match agent:<id> or human:<id>, got: ${target}`);
}

Type guard

function parseTargetSafe(target: string): { id: string; type: 'agent' | 'human' } | null {
  const m = /^(agent|human):([^:]+)$/.exec(target.trim());
  return m ? { type: m[1] as 'agent' | 'human', id: m[2] } : null;
}

Prevention

Build targets from typed values: `${type}:${id}` with type from a union
Validate target strings with a regex before passing to the claims CLI

When it happens

Trigger: Running a claims CLI command with --target coder-1 (no prefix), --target agent: (empty id), --target user:alice (unknown type 'user'), or --target 'agent:alice' when the intended prefix was human. Also targets containing extra colons silently truncate the id to the first segment, so malformed composite ids can fail downstream or here.

Common situations: Copy-pasting an id from a list output that shows bare names; scripts building targets via string concatenation with an undefined type variable; onboarding confusion about whether a claimant is registered as agent or human.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at v3/@claude-flow/claims/src/api/cli-commands.ts:174

  }

  const hours = Math.floor(diffMs / (1000 * 60 * 60));
  const minutes = Math.floor((diffMs % (1000 * 60 * 60)) / (1000 * 60));

  if (hours < 1) {
    return output.warning(`${minutes}m`);
  } else if (hours < 4) {
    return output.warning(`${hours}h ${minutes}m`);
  }

  return output.dim(`${hours}h ${minutes}m`);
}

function parseTarget(target: string): { id: string; type: ClaimantType } {
  // Format: agent:coder-1 or human:alice
  const [type, id] = target.split(':');
  if (!type || !id || (type !== 'agent' && type !== 'human')) {
    throw new Error(`Invalid target format: ${target}. Use agent:<id> or human:<id>`);
  }
  return { id, type: type as ClaimantType };
}

// ============================================
// List Subcommand
// ============================================

const listCommand: Command = {
  name: 'list',
  aliases: ['ls'],
  description: 'List issues',
  options: [
    {
      name: 'available',
      short: 'a',
      description: 'Show only unclaimed issues',
      type: 'boolean',

View on GitHub (pinned to fa13ee4ad6)