What causes "Environment variable ${envName} is empty or not set." in paperclipai/paperclip?

Export the variable in the same shell: `export MY_VAR=...; paperclipai auth challenge --token-env MY_VAR`.

paperclipai/paperclip · error · Error

Environment variable ${envName} is empty or not set.

Error message

Environment variable ${envName} is empty or not set.

What it means

Thrown by resolveChallengeToken() in auth.ts when --token-env names an environment variable that is either unset or empty/whitespace. The CLI deliberately reads from the named env var only when --token is absent, and treats an empty/unset env var as a hard failure rather than silently continuing without a secret.

Source

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

            handleCommandError(err);
          }
        }),
    );
  }
}

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

Export the variable in the same shell: `export MY_VAR=...; paperclipai auth challenge --token-env MY_VAR`.
Check the name: `printenv MY_VAR` should print a non-empty value.
Pass the value directly with --token if env wiring is unreliable.
In CI, ensure the secret is mapped to the env var in the runner config.

Example fix

// before
paperclipai auth challenge --token-env CHALL_TOKEN   # CHALL_TOKEN unset
// after
export CHALL_TOKEN=secret123
paperclipai auth challenge --token-env CHALL_TOKEN

Defensive patterns

Strategy: validation

Validate before calling

function resolveChallengeToken(opts: { token?: string; tokenEnv?: string }): string {
  const t = opts.token?.trim();
  if (t) return t;
  const envName = opts.tokenEnv?.trim();
  if (!envName) throw new Error('Pass --token or --token-env');
  const v = process.env[envName];
  if (typeof v !== 'string' || v.trim() === '') {
    throw new Error(`Env var ${envName} is unset/empty. Export it: export ${envName}=<secret>`);
  }
  return v.trim();
}

Try / catch

try { resolveChallengeToken(opts); }
catch (err) {
  const msg = err instanceof Error ? err.message : '';
  if (msg.endsWith('is empty or not set.')) {
    console.error(`Export the named env var, or pass --token directly.`);
    process.exit(2);
  }
  throw err;
}

Prevention

Prefer --token in CI to avoid env-wiring surprises; use --token-env only when secret managers inject reliably.
Validate with `printenv <NAME>` before running the command.
Beware shell scoping: export in the same shell, not a subshell.
Treat an empty secret as a hard failure, not a default.

When it happens

Trigger: Running `paperclipai auth challenge ... --token-env MY_VAR` where MY_VAR is not exported in the shell or is exported as the empty string. Typo in the variable name. CI job that forgot to `export` the secret.

Common situations: Secret manager did not inject the env var. Variable name typo. Shell scoping issue (set in a subshell, not visible to the CLI). CI masked-secret that resolves to empty.

Related errors

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