# Error Handling
Pathmaster is designed to handle errors gracefully and provide clear, helpful error messages. This guide explains common errors you might encounter and how to resolve them.
## Common Error Types
### Permission Errors
```
Error: Permission denied when modifying /etc/bin
```
**Cause**: You're trying to add a directory that requires elevated permissions.
**Solution**:
- For system directories, use sudo: `sudo pathmaster add /opt/special/bin`
- Add user-level directories instead (~/.local/bin) when possible
### Invalid Path Errors
```
Error: Directory does not exist: /home/user/nonexistent
```
**Cause**: You're trying to add a directory that doesn't exist.
**Solution**:
- Create the directory first: `mkdir -p /path/to/directory`
- Check for typos in the path
- Use tab-completion to avoid path errors
### Shell Configuration Errors
```
Error: Could not update shell configuration file ~/.bashrc
```
**Cause**: Pathmaster couldn't modify your shell configuration file.
**Solution**:
- Check file permissions: `ls -la ~/.bashrc`
- Ensure the file exists: `touch ~/.bashrc`
- Manually update your PATH if needed
### Backup Related Errors
```
Error: Could not create backup: Permission denied
```
**Cause**: Pathmaster couldn't create a backup before making changes.
**Solution**:
- Check permissions on the backup directory: `ls -la ~/.pathmaster`
- Create the directory if missing: `mkdir -p ~/.pathmaster/backups`
### Restore Errors
```
Error: No backup found with timestamp 20250401120000
```
**Cause**: You're trying to restore from a backup that doesn't exist.
**Solution**:
- List available backups: `pathmaster history`
- Choose an existing timestamp
- Use the most recent backup if unsure: `pathmaster restore`
## How Pathmaster Handles Errors
Pathmaster follows these principles for error handling:
1. **Safety First**: Pathmaster creates backups before making changes
2. **Validation**: Directories are validated before being added to PATH
3. **Rollback**: If an error occurs during an operation, pathmaster tries to roll back changes
4. **Clear Messages**: Error messages include specific details about what went wrong
5. **Exit Codes**: Pathmaster returns non-zero exit codes on error for script integration
## Debugging Techniques
When encountering persistent issues:
1. **Check PATH**: Run `pathmaster list` to see current PATH entries
2. **Check Invalid Entries**: Run `pathmaster check` to identify invalid directories
3. **Review Backups**: Run `pathmaster history` to see backup history
4. **Restore if Needed**: Run `pathmaster restore` to revert to a known good state
5. **Check Shell Config**: Examine your shell configuration file for issues
## Error Exit Codes
Pathmaster uses the following exit codes:
- **0**: Success
- **1**: General error
- **2**: Invalid input or usage
- **3**: Permission denied
- **4**: Resource not found
## Best Practices
- Always have a backup strategy beyond pathmaster's automatic backups
- Check your PATH occasionally with `pathmaster check`
- Flush invalid paths periodically with `pathmaster flush`
- Keep a simple, clean PATH to avoid conflicts