paperclipai/paperclip · error · Error

Agent reference is required

Error message

Agent reference is required

What it means

Thrown by resolveAgent in token.ts when the agent reference argument trims to an empty string. It is a pre-flight guard before any lookup attempt; the --agent option is logically required but reached here as empty.

Source

Thrown at cli/src/commands/client/token.ts:219

    board
      .command("revoke")
      .description("Revoke a board API key")
      .argument("<keyId>", "Board API key ID")
      .action(async (keyId: string, opts: BaseClientOptions) => {
        try {
          const ctx = resolveCommandContext(opts);
          const result = await ctx.api.delete<{ ok: true; keyId: string }>(apiPath`/api/board-api-keys/${keyId}`);
          printOutput(result ?? { ok: true, keyId }, { json: ctx.json });
        } catch (err) {
          handleCommandError(err);
        }
      }),
  );
}

async function resolveAgent(api: { get<T>(path: string): Promise<T | null> }, companyId: string, agentRef: string): Promise<Agent> {
  const trimmed = agentRef.trim();
  if (!trimmed) throw new Error("Agent reference is required");
  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(trimmed)) {
    const agent = await api.get<Agent>(apiPath`/api/agents/${trimmed}`);
    if (!agent || agent.companyId !== companyId) throw new Error(`Agent not found: ${agentRef}`);
    return agent;
  }
  const query = new URLSearchParams({ companyId });
  const agent = await api.get<Agent>(`${apiPath`/api/agents/${trimmed}`}?${query.toString()}`);
  if (!agent || agent.companyId !== companyId) throw new Error(`Agent not found: ${agentRef}`);
  return agent;
}

function resolveBoardKeyExpiresAt(opts: BoardTokenOptions): Date | null | undefined {
  if (opts.neverExpires) return null;
  if (opts.expiresAt?.trim()) {
    const date = new Date(opts.expiresAt.trim());
    if (!Number.isFinite(date.getTime())) throw new Error(`Invalid --expires-at value: ${opts.expiresAt}`);
    return date;
  }

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Provide a non-empty agent ID, shortname, or name: --agent <value>.
2. If scripting, guard the env var before invoking the CLI.
3. Use --agent with a UUID for the most direct resolution.

Example fix

// before
--agent ""
// after
--agent "01f3c2d4-..."  # or an agent shortname

const agentRef = (opts.agent ?? "").trim();
if (!agentRef) {
  console.error("--agent is required (ID, shortname, or name).");
  process.exit(1);
}

function isNonEmptyAgentRef(value: string | undefined): value is string {
  return typeof value === "string" && value.trim().length > 0;
}

When it happens

Trigger: Calling `token agent create` with `--agent ""`, `--agent " "`, or omitting --agent in a code path that does not declare it requiredOption. resolveAgent trims and rejects empty before UUID/name resolution.

Common situations: A wrapper script passing an unset env var (`--agent "$AGENT_ID"` with AGENT_ID empty), or a command alias that dropped the argument.

Related errors

• Invalid --adapter-override "${raw}". Use slug=type.
• Invalid ${flag} "${raw}". Use ${format}.
• Agent not found: ${agentRef}
• Invalid --expires-at value: ${opts.expiresAt}
• Invalid --ttl-days value: ${opts.ttlDays}

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/616f0431e54f5f2b. Report an issue: GitHub.