What causes "Challenge secret is required. Pass --token or --token-env." in paperclipai/paperclip?

Pass --token directly: `paperclipai auth challenge --token `.

paperclipai/paperclip · error · Error

Challenge secret is required. Pass --token or --token-env.

Error message

Challenge secret is required. Pass --token or --token-env.

What it means

Thrown by resolveChallengeToken() when neither --token nor --token-env was supplied (or both are empty). This is the auth-challenge command's hard requirement: a challenge secret must come from one of those two sources. Reached only when both paths are absent (if --token-env is given but empty, [15] fires instead).

Source

Thrown at cli/src/commands/client/auth.ts:202

        }),
    );
  }
}

function parseJson(value: string): unknown {
  return JSON.parse(value) as unknown;
}

function resolveChallengeToken(opts: AuthChallengeOptions): string {
  const token = opts.token?.trim();
  if (token) return token;
  const envName = opts.tokenEnv?.trim();
  if (envName) {
    const envValue = process.env[envName]?.trim();
    if (envValue) return envValue;
    throw new Error(`Environment variable ${envName} is empty or not set.`);
  }
  throw new Error("Challenge secret is required. Pass --token or --token-env.");
}

View on GitHub (pinned to 67001ec6eb)

Solutions

Pass --token directly: `paperclipai auth challenge --token <secret>`.
Or point to an env var: `--token-env MY_VAR` after exporting it.
Confirm the secret value matches what the server/operator expects for the challenge.

Example fix

// before
paperclipai auth challenge --client-name my-cli
// after
paperclipai auth challenge --client-name my-cli --token $CHALLENGE_SECRET

Defensive patterns

Strategy: validation

Validate before calling

function requireChallengeToken(opts: { token?: string; tokenEnv?: string }): string {
  if (opts.token?.trim()) return opts.token.trim();
  if (opts.tokenEnv?.trim()) { /* caller resolves env */ throw new Error('use --token-env path'); }
  throw new Error('Challenge secret required. Pass --token <secret> or --token-env <NAME>.');
}

Try / catch

try { resolveChallengeToken(opts); }
catch (err) {
  const msg = err instanceof Error ? err.message : '';
  if (msg === 'Challenge secret is required. Pass --token or --token-env.') {
    console.error(msg); process.exit(2);
  }
  throw err;
}

Prevention

Always pass exactly one of --token / --token-env for auth challenge.
Document the expected secret source in your runbook.
Fail fast in wrappers: assert one of the two is set before invoking the CLI.

When it happens

Trigger: Running `paperclipai auth challenge ...` with neither --token nor --token-env. Both flags supplied empty. The command needs the shared challenge secret to mint/approve a cli-auth challenge.

Common situations: User assumed the secret would be picked up from a default env var. Forgot to pass either flag. Help text not read.

Related errors

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