Troubleshooting

Check the working directory, the workspace’s selected ingredient, and the command’s help. Do not post local keys, credential files, revealed values, or real secrets in an issue.

The executable is missing or will not build

If your shell cannot find ramenv, check Cargo’s binary directory, usually ~/.cargo/bin, and add it to PATH.

If compilation fails, use a recent stable Rust toolchain and the documented --locked installation command. Edition 2024 support alone may not satisfy the pinned dependencies. See installation.

No workspace, vault, or environment is found

Ordinary commands need .ramenv.vault.toml in the current directory. Workspace discovery walks upward, but it does not automatically select a service vault elsewhere.

• For a single repository, initialize from the application directory.
• For a monorepo, initialize the root workspace, then register each service with ramenv init service.
• Run ordinary commands from the service directory, not a root containing only workspace metadata.
• create-env creates an empty environment only in the current vault; it does not fill sibling vaults.

See workspaces. Do not reinitialize as a substitute for restoring missing keys or migrating ingredients.

Vault integrity or decryption fails

Check that the vault and workspace match the local keys or the cloud refs and their remote key versions. Restore a known-good matching set if necessary.

Manual environment-data edits and incompatible merges can invalidate the HMAC. Use CLI commands to change values. Validation-only edits are excluded from the HMAC and do not need re-signing.

You cannot recover a missing encryption key from ciphertext or recreate a deleted remote key version from its ref. Check key backups and the provider’s retention rules before rotating or removing environments.

Cloud login succeeds but key access fails

Check which identity ramenv selected, then check its secret-store permissions, the saved provider location, and network restrictions.

Provider	Common checks
AWS	Stale environment access keys can override AWS_PROFILE; renew SSO and check IAM/KMS access in the saved region.
Azure	Select developer-tools for local CLI login; incomplete identity variables can cause errors. Check data-plane permissions and vault networking.
Google	Use ADC login, not only gcloud auth login; check GOOGLE_APPLICATION_CREDENTIALS, API enablement, saved project, and quota requirements.

Authorization errors do not make ramenv try a different identity. Use the AWS, Azure, or Google guide to fix the selected one.

Changing AWS_REGION, an Azure account, or gcloud’s active project does not relocate a workspace’s saved key store.

Validation fails or startup ignores rules

run does not validate automatically. Gate it with a separate successful validate command.

Check required fields, rule types, bounds, and patterns. Rules apply across environments in the current vault. A deleted value may still have a required rule. String lengths are bytes; regex patterns need anchors for whole-value matching.

Extra variables without rules are not rejected. The email rule performs basic checks, not full email-address validation. See validation.

Values are unexpected in the application

run uppercases variable names and overrides matching inherited variables. Other inherited variables remain available. Use uppercase names to avoid case collisions.

Make sure you selected the right environment and are in the correct service directory. Each service has its own values, even when it shares workspace keys. Use list locally with care; do not turn on --reveal in shared CI logs.

Onboarding imports unselected variables as plaintext and overwrites matching keys. Review the vault if values changed after an import.

A removed environment cannot be recreated

Cloud providers have different deletion behavior:

• AWS schedules deletion with a recovery window; a pending-deletion name cannot immediately be reused.
• Azure soft-delete and purge protection may block reuse until recovery, permitted purge, or retention expiry.
• Google removal deletes the entire secret and all versions.

Environment removal deletes the whole key secret. Check your provider’s versions-and-deletion section before retrying.

Report a bug safely

Include the command, non-secret error text, OS, ingredient, relevant file layout, and reproduction steps. Redact account identifiers where appropriate and replace sensitive values with clearly fake examples.

Never attach .ramenv.keys, cloud credentials, token files, or decrypted secrets. Report issues in the ramenv repository.