Vault Issues

Troubleshooting

Vault Issues

Solutions for vault access, corruption, and recovery issues.

Vault Access Issues

“Invalid Master Password” Error

Symptom: Password rejected when accessing vault

Cause: Incorrect password or vault corruption

Solutions:

Verify password
- Check caps lock
- Try typing slowly
- Copy-paste if stored elsewhere

Check keychain entry

# macOS: View in Keychain Access
# Linux: View in Seahorse/KWallet
# Windows: View in Credential Manager

Restore from backup

# If vault is corrupted
cp ~/.pass-cli/vault.enc.backup ~/.pass-cli/vault.enc

Try manual backup

# If you have manual backup
cp ~/backups/vault-20250120.enc ~/.pass-cli/vault.enc

“Vault File Corrupted” Error

Symptom: Cannot decrypt vault, corruption detected

Cause: File corruption from crash or disk error

Solutions:

Restore automatic backup

# Check if backup exists
ls -la ~/.pass-cli/vault.enc.backup

# Restore
cp ~/.pass-cli/vault.enc.backup ~/.pass-cli/vault.enc

# Test access
pass-cli list

Restore manual backup

# List available backups
ls -la ~/backups/vault-*.enc

# Restore most recent
cp ~/backups/vault-20250120.enc ~/.pass-cli/vault.enc

If no backup available

# Unfortunately, corrupted vault without backup is unrecoverable
# Initialize new vault
mv ~/.pass-cli/vault.enc ~/.pass-cli/vault.enc.corrupted
pass-cli init
# Re-add credentials manually

“Permission Denied” Reading Vault

Symptom: Cannot read vault file

Cause: File permission issues

Solutions:

macOS/Linux:

# Check permissions
ls -la ~/.pass-cli/vault.enc

# Fix permissions (should be 0600)
chmod 600 ~/.pass-cli/vault.enc

# Fix ownership
sudo chown $USER:$USER ~/.pass-cli/vault.enc

Windows:

# Check ACL
Get-Acl "$env:USERPROFILE\.pass-cli\vault.enc" | Format-List

# Reset permissions to current user
$acl = Get-Acl "$env:USERPROFILE\.pass-cli\vault.enc"
$acl.SetAccessRuleProtection($true, $false)
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
    $env:USERNAME, "FullControl", "Allow"
)
$acl.AddAccessRule($rule)
Set-Acl "$env:USERPROFILE\.pass-cli\vault.enc" $acl

Vault Recovery

Forgot Master Password

Symptom: Cannot remember master password

Options:

Use BIP39 Recovery Phrase (if enabled during init)
```
# Recover access with recovery phrase
pass-cli change-password --recover
```
Requirements:
- Recovery phrase must have been enabled during pass-cli init
- You must have your 24-word recovery phrase written down
- You’ll need to provide 6 random words from the phrase
Process:
1. Run pass-cli change-password --recover
2. System prompts for 6 random words from your 24-word phrase
3. If verification succeeds, you can set a new master password
4. Vault is re-encrypted with new password
For detailed recovery instructions, see Recovery Phrase Guide.
Check keychain (if still accessible)
- macOS: Keychain Access → search “pass-cli”
- Linux: Seahorse → search “pass-cli”
- Windows: Credential Manager → search “pass-cli”
Try to remember
- Try common variations
- Check password manager if stored there
- Check secure notes

If recovery phrase not available or wasn’t enabled

# Vault is unrecoverable without master password or recovery phrase
# Start fresh
mv ~/.pass-cli/vault.enc ~/.pass-cli/vault.enc.lost
pass-cli init
# Re-add credentials from services

Prevention:

[OK] Enable recovery phrase during init (it’s enabled by default)
[OK] Write recovery phrase on paper and store in safe
[OK] Write master password in secure location
[OK] Store master password in another password manager
[OK] Keep backup of master password

Vault File Deleted

Symptom: Vault file missing

Solutions:

Check trash/recycle bin

Restore from backup

# Automatic backup
cp ~/.pass-cli/vault.enc.backup ~/.pass-cli/vault.enc

# Manual backup
cp ~/backups/vault-*.enc ~/.pass-cli/vault.enc

Restore from cloud sync (if syncing vault)

# From Dropbox, Google Drive, etc.
cp ~/Dropbox/vault.enc ~/.pass-cli/vault.enc

If no backup

# Unfortunately, must start over
pass-cli init

Corrupt Vault Recovery

Symptom: Vault fails to decrypt or shows corruption errors

Solutions:

Try automatic backup

cp ~/.pass-cli/vault.enc.backup ~/.pass-cli/vault.enc
pass-cli list

Try older backups

# List backups by date
ls -lt ~/backups/vault-*.enc

# Try each, newest first
cp ~/backups/vault-20250120.enc ~/.pass-cli/vault.enc
pass-cli list

Attempt partial recovery (advanced)

# Examine vault file
hexdump -C ~/.pass-cli/vault.enc | head -n 20

# Check file size
ls -la ~/.pass-cli/vault.enc

# If file is obviously truncated or wrong size
# Recovery likely impossible, use backup

Vault Save Interrupted / Orphaned Temporary Files

Symptom: Save operation interrupted (crash, power loss, kill signal) or temporary files (vault.enc.tmp.*) left behind

Cause: Atomic save process interrupted mid-operation

Background: Pass-CLI uses an atomic save pattern to protect against corruption:

Writes to temporary file (vault.enc.tmp.TIMESTAMP.RANDOM)
Verifies temp file is decryptable
Renames current vault to backup (vault.enc.backup)
Renames temp file to vault (vault.enc)

If interrupted, your vault remains safe at step 1-2 (old vault unchanged) or step 3-4 (backup exists).

Solutions:

Check vault status after interruption

# Check which files exist
ls -la ~/.pass-cli/

# Files you may see:
# vault.enc                  - Current vault (may be old or new)
# vault.enc.backup           - Previous vault state
# vault.enc.tmp.20250109-*   - Orphaned temp file from crash

Verify current vault is accessible

# Try to unlock vault
pass-cli list

# If this works, vault is fine
# Orphaned temp files can be safely deleted

If current vault fails to unlock

# Check if backup exists
ls -la ~/.pass-cli/vault.enc.backup

# Restore from backup (contains N-1 state)
cp ~/.pass-cli/vault.enc.backup ~/.pass-cli/vault.enc

# Test restored vault
pass-cli list

# You may have lost your most recent changes,
# but vault is recovered

Clean up orphaned temporary files

# List temp files
ls -la ~/.pass-cli/vault.enc.tmp.*

# Remove orphaned temp files (safe after vault verified)
rm ~/.pass-cli/vault.enc.tmp.*

# Note: pass-cli automatically cleans these up
# on next save operation

Identify what was lost

# If you had to restore from backup, you lost:
# - Most recent credential addition/update/deletion
# - Most recent password change (if in progress)

# Check audit log if enabled
tail -20 ~/.pass-cli/audit.log

# Last successful operation shown in audit log

Recovery Decision Matrix:

vault.enc accessible → Keep it, delete temp files
vault.enc corrupted, vault.enc.backup exists → Restore backup
Both corrupted, vault.enc.tmp.* exists → Try unlocking temp file
All corrupted → Use external backup or reinitialize

Prevention:

Regular backups to external location
Don’t force-kill pass-cli during save operations
Ensure sufficient disk space before operations
Use UPS for desktop systems

Understanding Vault Backup Lifecycle

Q: When is vault.enc.backup created and removed?

A: Backup lifecycle with atomic save:

Backup Created: During save operation

# Before save:
vault.enc (old data)

# During save:
vault.enc.tmp.20250109-143022.a1b2c3 (new data being written)

# After verification passes:
vault.enc → renamed to → vault.enc.backup (old data)
vault.enc.tmp.* → renamed to → vault.enc (new data)

Backup Removed: After next successful unlock

# On next vault unlock:
# - Vault decrypts successfully
# - Backup is removed (no longer needed)
# - Only vault.enc remains

Why this pattern?
- Backup proves old vault was valid
- If new vault fails to decrypt, backup still available
- After successful unlock, new vault proven good
- Backup cleanup saves disk space

Implications:

Backup contains N-1 generation (one save ago)
If save fails, backup has your last good state
If vault becomes corrupted between saves, backup may help
Backup removed after successful unlock (not kept permanently)

Manual Backup Recommended:

# Backup before risky operations
cp ~/.pass-cli/vault.enc ~/backups/vault-$(date +%Y%m%d).enc

# Automated daily backup
echo '0 0 * * * cp ~/.pass-cli/vault.enc ~/backups/vault-$(date +\%Y\%m\%d).enc' | crontab -

Installation Issues Keychain Issues