paperclipai/paperclip · error · Error

Environment variable ${opts.valueEnv} is empty or unset.

Error message

Environment variable ${opts.valueEnv} is empty or unset.

What it means

`readValueFromOptions` takes the `--value-env` branch (only `--value-env` was provided) and reads `process.env[<name>]`. If that variable is unset or empty, it throws naming the variable. Distinct from error 89 only in location (secrets module) and message wording.

Source

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

      secretId,
      version: "latest",
    };
  }
  return next;
}

function asRecord(value: unknown): Record<string, unknown> | null {
  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
  return value as Record<string, unknown>;
}

function readValueFromOptions(opts: { value?: string; valueEnv?: string }): string {
  if (opts.value !== undefined && opts.valueEnv !== undefined) {
    throw new Error("Use only one of --value or --value-env.");
  }
  if (opts.valueEnv !== undefined) {
    const value = process.env[opts.valueEnv];
    if (!value) throw new Error(`Environment variable ${opts.valueEnv} is empty or unset.`);
    return value;
  }
  if (opts.value !== undefined) return opts.value;
  throw new Error("Secret value is required. Pass --value or --value-env.");
}

function renderDeclaration(input: CompanyPortabilityEnvInput): Record<string, unknown> {
  const scope = input.agentSlug
    ? `agent:${input.agentSlug}`
    : input.projectSlug
      ? `project:${input.projectSlug}`
      : "company";
  return {
    key: input.key,
    scope,
    kind: input.kind,
    requirement: input.requirement,
    portability: input.portability,

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Export the named variable: `export FOO=<secret>`
2. Verify the variable name spelling/case matches what is exported
3. In CI, confirm the secret is mapped to that exact env var name in the step

Example fix

# before
paperclipai secrets set ... --value-env SECRET_VALUE   # SECRET_VALUE unset
# after
export SECRET_VALUE=<secret>
paperclipai secrets set ... --value-env SECRET_VALUE

function readEnvValueOrThrow(varName: string): string {
  const value = process.env[varName];
  if (!value) throw new Error(`Environment variable ${varName} is empty or unset.`);
  return value;
}
const value = opts.valueEnv ? readEnvValueOrThrow(opts.valueEnv) : opts.value;

When it happens

Trigger: Running a secret value command with `--value-env FOO` where `FOO` is not exported or is empty in the current process.

Common situations: Env var typo or wrong case; secret not injected in CI; `.env` not sourced; var renamed but flag not updated.

Related errors

• Environment variable ${envName} is empty or not set.
• Environment variable ${opts.apiKeyEnv.trim()} is not set
• Challenge secret is required. Pass --token or --token-env.
• Invalid --include value. Use one or more of: company,agents,
• Use only one of --value or --value-env.

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