What causes "${label} is required" in paperclipai/paperclip?

Pass the flag named in the message with a non-empty trimmed value

${label} is required

Error message

${label} is required

What it means

The private `required` helper throws this when an option value is missing or whitespace-only after trimming. The label is the CLI flag name (e.g. "--profile-key"), so the message tells you exactly which flag was omitted. It is a fail-fast input validation guard in `validateManagedAgentSetup` before any network calls are made.

Source

Thrown at cli/src/commands/managed-agent.ts:60

  apiKeySecretId: string;
  model: string;
  agentId?: string;
  agentVersion?: string;
  environmentId?: string;
  defaultMaxListCostUsd: number;
}

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

function record(value: unknown): Record<string, unknown> {
  return value && typeof value === "object" && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : {};
}

function required(value: string | undefined, label: string): string {
  const normalized = value?.trim() ?? "";
  if (!normalized) throw new Error(`${label} is required`);
  return normalized;
}

export function validateManagedAgentSetup(
  options: ManagedAgentSetupOptions,
  env: NodeJS.ProcessEnv = process.env,
): ValidatedSetup {
  const anthropicApiKey = env.ANTHROPIC_API_KEY?.trim();
  if (!anthropicApiKey) {
    throw new Error("ANTHROPIC_API_KEY is required in the CLI process environment");
  }
  if (!options.acknowledgeRetention) {
    throw new Error(
      "Pass --acknowledge-retention to enable the stateful beta Managed Agents service",
    );
  }

  const profileKey = required(options.profileKey, "--profile-key");

View on GitHub (pinned to 5716fe907e)

Solutions

Pass the flag named in the message with a non-empty trimmed value
Check the shell variable feeding the flag actually resolves (echo it before running)
Run `--help` on the managed-agent command to see required flags
If calling validateManagedAgentSetup directly, populate the options object field before invoking

Example fix

// before
spawn("paperclip", ["managed-agent", "--profile-key", profileKey]);
// after
spawn("paperclip", ["managed-agent", "--profile-key", profileKey, "--display-name", name, "--api-key-secret-id", secretId, "--model", "claude-sonnet-5"]);

Defensive patterns

Strategy: validation

Validate before calling

const flags = { profileKey, displayName, apiKeySecretId, model };
const missing = Object.entries(flags).filter(([, v]) => !v?.trim()).map(([k]) => k);
if (missing.length) throw new Error(`Missing required flags: ${missing.join(", ")}`);

Type guard

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

Try / catch

try {
  await setupManagedAgent(opts);
} catch (err) {
  if (err instanceof Error && err.message.endsWith("is required")) {
    console.error(`Usage error: ${err.message}`); process.exitCode = 2;
  } else throw err;
}

Prevention

Build command lines from a single typed options object so no flag can be dropped
Validate all required values before spawning the CLI
Check shell variables are non-empty before interpolation (set -u in bash)
Keep command templates in one place and update them when flags change

When it happens

Trigger: Calling `paperclip managed-agent` setup without supplying one of --profile-key, --display-name, --api-key-secret-id, or --model, or supplying one whose value is empty or only whitespace (e.g. `--display-name " "`). Also hit programmatically by calling `validateManagedAgentSetup` with an options object where the corresponding string field is undefined.

Common situations: Scripted invocations where an interpolated shell variable is empty; forgetting a flag after copying an example command; CI secrets that resolve to empty strings; typo'd flag names so commander leaves the option undefined.

Related errors

AI-assisted analysis of paperclipai/paperclip@5716fe907e (2026-09-02). Data as JSON: /api/errors/5d5d13f9563effa3. Report an issue: GitHub.