-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
sysid edited this page Mar 6, 2026
·
5 revisions
Solutions to common rsenv issues.
rsenv isn't in your PATH:
# If installed via cargo, add to PATH
export PATH="$HOME/.cargo/bin:$PATH"
# Add to shell config for persistence
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc# Update Rust
rustup update
# Clean and retry
cargo clean
cargo install rsenvProject doesn't have a vault:
# Initialize
rsenv init vault
# Or check if you're in the right directory
pwd
ls -la .envrc# Check symlink target
ls -la .envrc
# If vault exists but symlink is broken
rsenv init vault # Will detect existing vault
# If vault was deleted
rsenv init vault # Creates new vaultIf you moved your project directory:
# Symlinks may be broken if relative
# Reinitialize with absolute paths
rsenv init reset
rsenv init vault --absolute# Check current vault
rsenv info
# Reset and reinitialize
rsenv init reset
rsenv init vaultParent env file doesn't exist or path is wrong:
# Check the rsenv directive
cat problematic.env | grep "# rsenv:"
# Verify parent exists
ls -la $(dirname problematic.env)/
# Check path expansion
echo $RSENV_VAULT# Check hierarchy order
rsenv env files leaf.env
# View tree
rsenv env tree
# Build and inspect
rsenv env build leaf.envYour environment files have a cycle:
# Check for cycles manually
# a.env: # rsenv: b.env
# b.env: # rsenv: a.env <- cycle!
# Remove circular reference
vim offending.envdirenv might need to be allowed:
# Allow direnv
direnv allow
# Check if .envrc is executable/readable
ls -la .envrc
# Force reload
direnv reloadFile is already a symlink to vault:
# Check file status
ls -la path/to/file
# If you need to re-guard, restore first
rsenv guard restore path/to/file
rsenv guard add path/to/fileCan only guard files inside the project directory:
# Check project root
rsenv info
# File must be under this directory
pwd
ls -la file-to-guard# Check vault location
ls -la $RSENV_VAULT/guarded/
# The path mirrors project structure
ls -la $RSENV_VAULT/guarded/config/secrets.yaml# Check if file is actually a symlink
ls -la path/to/file
# Check vault file exists
ls -la $(readlink path/to/file)
# Manual restore if needed
cp $RSENV_VAULT/guarded/path/to/file ./path/to/file
rm path/to/file # Remove symlink first
mv vault-file ./path/to/file- if a file accidentally has been created at a location which is currently swapped out, just
initthe file/directory. It will be added to the vault at the swapped-out parent directory.
rsenv swap init <file-path|dir-path>Another host has the file swapped in:
# Check status
rsenv swap status
# Swap out on the other host first, or manually remove the marker file
rm file.yml.otherhost.rsenv_active
rsenv swap in file.ymlInitialize it first:
rsenv swap init path/to/fileIf rsenv swap status shows duplicate entries (e.g., file and file with trailing space),
this is caused by paths containing invisible whitespace characters (often non-breaking spaces
from copy-paste).
Fixed in v5.1.0: rsenv now automatically sanitizes paths by stripping trailing whitespace.
To clean up existing duplicates:
# List vault swap directory to identify duplicates
ls -la $RSENV_VAULT/swap/ | cat -A # Shows special chars as M-BM-
# Delete the spurious directories (with NBSP shown as \xc2\xa0)
rm -rf $RSENV_VAULT/swap/$'dirname\xc2\xa0'Your GPG key isn't available:
# List your keys
gpg --list-secret-keys
# Import if needed
gpg --import /path/to/key.asc
# Check configured key matches
rsenv config show | grep gpg_keyNo GPG key configured:
# Edit config
vim ~/.config/rsenv/rsenv.toml
# Add:
[sops]
gpg_key = "YOUR_FINGERPRINT"Check your encryption patterns:
# Show config
rsenv config show
# Check what would be encrypted
rsenv sops status
# List files manually
ls -la $RSENV_VAULT/*.env# Check key used to encrypt
sops --decrypt --verbose file.enc 2>&1 | grep key
# Verify you have that key
gpg --list-secret-keys | grep FINGERPRINTSyntax error in .envrc:
# Check .envrc content
cat .envrc
# Remember: it's a symlink
cat $RSENV_VAULT/dot.envrc
# Fix and reload
vim $RSENV_VAULT/dot.envrc
direnv allow# Allow the .envrc
direnv allow
# If still blocked, check direnv config
cat ~/.config/direnv/direnv.toml# Force reload
direnv reload
# Or leave and re-enter directory
cd .. && cd -# Check paths
rsenv config path
# Create if missing
rsenv config init --global# Verify export
echo $RSENV_VAULT_BASE_DIR
# Must be exported, not just set
export RSENV_VAULT_BASE_DIR=~/my-vaults# Check syntax
cat ~/.config/rsenv/rsenv.toml
# Common issues:
# - Missing quotes around values with special chars
# - Incorrect array syntax (use ["a", "b"])
# - Tabs instead of spacesrsenv --verbose <command>rsenv --version
sops --version
gpg --version
direnv --versionIf all else fails:
# Backup vault first!
cp -r $RSENV_VAULT ~/vault-backup
# Reset project
rsenv init reset
# Delete vault
rm -rf $RSENV_VAULT
# Start fresh
rsenv init vault- Core Concepts - Understanding how rsenv works
- Configuration - Config options and precedence
If you've found a bug:
- Check existing issues: https://github.com/sysid/rsenv/issues
- Include:
- rsenv version (
rsenv --version) - OS and version
- Steps to reproduce
- Expected vs actual behavior
- Relevant config (redact secrets!)
- rsenv version (
Collect for bug reports:
rsenv --version
rsenv info
rsenv config show
rsenv config path
ls -la .envrc
echo $RSENV_VAULTrsenv Documentation