What causes "environment variable %q is missing or empty" in larksuite/cli?

Export the environment variable with a non-empty value before running the process (export DB_PASSWORD=...)

environment variable %q is missing or empty

Error message

environment variable %q is missing or empty

What it means

resolveEnvRef reads the allowlisted environment variable via getenv and throws this error when the value is empty or unset. The library requires a non-empty value because an empty secret is almost always a misconfiguration rather than a legitimate secret. This is thrown after the allowlist check passed.

Source

Thrown at internal/binding/secret_resolve.go:101

// resolveEnvRef handles {source:"env"} SecretRef.
func resolveEnvRef(ref *SecretRef, pc *ProviderConfig, getenv func(string) string) (string, error) {
	// Check allowlist if configured
	if len(pc.Allowlist) > 0 {
		allowed := false
		for _, name := range pc.Allowlist {
			if name == ref.ID {
				allowed = true
				break
			}
		}
		if !allowed {
			return "", fmt.Errorf("environment variable %q is not allowlisted in provider", ref.ID)
		}
	}

	value := getenv(ref.ID)
	if value == "" {
		return "", fmt.Errorf("environment variable %q is missing or empty", ref.ID)
	}
	return value, nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Export the environment variable with a non-empty value before running the process (export DB_PASSWORD=...)
Check for typos in the variable name and confirm with `env | grep NAME` in the same context the process runs
If using an env file, ensure it is actually loaded (e.g. --env-file, dotenv import) and contains the key
If empty is legitimately valid, store the value in a non-env secret source instead of relying on an empty env var

Example fix

// before (shell)
./app  # DB_PASSWORD unset

// after (shell)
export DB_PASSWORD="s3cr3t"
./app

Defensive patterns

Strategy: validation

Validate before calling

// check before calling the library
if v := os.Getenv("DB_PASSWORD"); v == "" {
    return fmt.Errorf("DB_PASSWORD must be exported and non-empty before startup")
}

Try / catch

val, err := resolveSecretRef(ctx, ref)
if err != nil {
    if strings.Contains(err.Error(), "missing or empty") {
        return fmt.Errorf("startup aborted: export %s in your environment or env-file", ref.ID)
    }
    return err
}

Prevention

Load your env file explicitly (.env, --env-file) and verify with `env | grep` in the same shell/user context the process runs in
Declare required env vars in a startup checklist or fail-fast config validation
In CI, define the secret in the job's secret store and map it to the exact variable name

When it happens

Trigger: resolveSecretRef is called with a SecretRef whose ID is allowlisted, but os.LookupEnv/getenv returns "" — the variable is not exported in the process environment, is exported as an empty string, or the process was started without it (e.g. missing --env-file).

Common situations: Running locally without the .env file the deploy environment uses; CI job missing a secret definition; variable exported in a shell that didn't propagate to the child process; docker/systemd unit not passing the var through; var set to empty string by a previous script step.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/371c54a3901b8111. Report an issue: GitHub.