Troubleshooting

Common issues, error messages, and solutions for Vault CLI

Common Errors

This page covers common error messages, their causes, and how to resolve them.

Please pass in an argument

Error Message:

Please pass in an argument

Source: Program.cs line 11

Cause: You ran the vault command without any arguments.

Solution: Vault requires at least one command argument. Provide a valid command:

vault add mykey myvalue
vault get mykey
vault list

See the Commands documentation for available commands.

Please enter a valid command, could not execute

Error Message:

Please enter a valid command, could not execute

Source: KVSTORE.cs lines 138, 154

Cause: Either the command name is invalid, or the command was called with the wrong number of arguments.

Solution: Verify you’re using a valid command with the correct arguments:

Command	Arguments	Example
add	2 (key, value)	vault add mykey myvalue
remove	1 (key)	vault remove mykey
update	2 (key, value)	vault update mykey newvalue
get	1 (key)	vault get mykey
list	0	vault list

Examples of invalid usage:

# Wrong: missing value argument
vault add mykey

# Wrong: too many arguments
vault get mykey extraarg

# Wrong: invalid command name
vault delete mykey

Please {command} is not a valid command

Error Message:

Please {command} is not a valid comand

Source: KVSTORE.cs line 194 (Note: source has typo “comand”)

Cause: The command name you entered doesn’t match any of the supported commands.

Solution: Use one of the five supported commands:

• add
• remove
• update
• get
• list

# Correct
vault add mykey myvalue

# Incorrect - use 'remove' not 'delete'
vault delete mykey

Key: {key} does not exist in db

Error Message:

Key: {key} does not exist in db

Source: KVSTORE.cs line 85

Cause: You tried to update a key that doesn’t exist in the database.

Solution:

1. Check if the key exists:

vault list

2. If the key doesn’t exist, use add instead of update:

vault add mykey myvalue

3. If the key should exist, verify the key name (keys are case-sensitive):

vault add MyKey value    # Different from 'mykey'
vault add mykey value

The update command only modifies existing keys. To add a new key, use the add command.

Database Issues

Permission denied when accessing database

Symptoms:

• Cannot read or write to database
• Permission errors when running commands
• Database file cannot be created

Cause: Insufficient permissions on the .kvstore directory or store.db file.

Solution:

1. Check permissions on the database directory:

ls -la ~/.kvstore/

2. Ensure you have read/write permissions:

macOS/Linux

chmod 755 ~/.kvstore
chmod 644 ~/.kvstore/store.db

3. If the issue persists, try recreating the database:

# Backup first
cp ~/.kvstore/store.db ~/.kvstore/store.db.backup

# Remove and recreate
rm ~/.kvstore/store.db
vault list  # Creates new database

Database is locked

Error Message:

SQLite Error: database is locked

Cause: Another process is currently accessing the database, or a previous process didn’t close the connection properly.

Solution:

1. Check for running Vault processes:

macOS/Linux

ps aux | grep vault

2. Wait a few seconds and try again (connections auto-close)

3. If the issue persists, reboot your machine to clear all locks

Do not manually delete lock files, as this can corrupt the database. Let SQLite manage its own locking mechanism.

Database corruption / malformed database

Error Message:

SQLite Error: database disk image is malformed

Cause: The database file has been corrupted, possibly due to:

• Unexpected system shutdown
• Disk errors
• Manual file modification
• Running out of disk space

Solution:

1. Try recovery first (if you have a backup):

# Restore from backup
cp ~/.kvstore/store.db.backup ~/.kvstore/store.db
vault list

2. Use SQLite recovery tools:

# Dump data from corrupted database
sqlite3 ~/.kvstore/store.db ".dump" > vault-dump.sql

# Create new database
rm ~/.kvstore/store.db
sqlite3 ~/.kvstore/store.db < vault-dump.sql

3. Last resort - reset the database:

This will delete all your stored keys and values permanently.

rm ~/.kvstore/store.db
vault list  # Creates fresh database

Installation Issues

vault command not found

Symptoms:

• Running vault returns “command not found”
• Tool appears installed but doesn’t run

Cause: The .NET global tools directory is not in your PATH.

Solution:

1. Verify the tool is installed:

dotnet tool list --global

2. Check your PATH includes the .NET tools directory:

macOS/Linux

echo $PATH | grep .dotnet

# Add to PATH if missing (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$HOME/.dotnet/tools"

3. Restart your terminal after modifying PATH

.NET runtime not found

Error Message:

You must install .NET to run this application

Cause: .NET 9.0 or later is not installed on your system.

Solution:

1. Download and install .NET 9.0 or later from https://dotnet.microsoft.com/download

2. Verify installation:

dotnet --version

3. Reinstall Vault after .NET is installed:

dotnet tool install --global Vault.10.25.25.001

Resetting Vault

If you need to completely reset Vault and start fresh:

This will permanently delete all stored keys and values. Make sure to back up any important data first.

Complete Reset

macOS/Linux

# Backup (optional)
cp ~/.kvstore/store.db ~/vault-backup-$(date +%Y%m%d).db

# Delete database
rm ~/.kvstore/store.db

# Verify reset
vault list
# Output: (no keys)

The database will be automatically recreated the next time you run any Vault command.

Debug Steps

When troubleshooting issues, follow these steps:

1. Verify Installation

# Check tool is installed
dotnet tool list --global | grep -i vault

# Check .NET version
dotnet --version

2. Check Database Location

# Verify database exists
ls -la ~/.kvstore/

# Check database file size
du -h ~/.kvstore/store.db

3. Test Basic Operations

# Test each command
vault list
vault add testkey testvalue
vault get testkey
vault update testkey newvalue
vault remove testkey

4. Examine Database Directly

You can use the SQLite CLI to inspect the database:

# Install sqlite3 if needed
sqlite3 ~/.kvstore/store.db

# Run queries
SQLite> .tables
SQLite> .schema store
SQLite> SELECT * FROM store;
SQLite> .quit

5. Check for Conflicting Processes

# Check for processes holding the database
lsof ~/.kvstore/store.db  # macOS/Linux

If you’re still experiencing issues after following these steps, consider resetting the database or checking the GitHub repository for known issues.

Getting Help

If you’ve tried all troubleshooting steps and still need assistance:

1. Check the database location is correct for your OS
2. Verify file permissions on ~/.kvstore/ directory
3. Ensure you’re using .NET 9.0 or later
4. Try with a fresh database (backup first)
5. Review error messages carefully - they indicate the specific issue

Most issues can be resolved by:

• Using the correct command syntax
• Ensuring proper file permissions
• Resetting a corrupted database