# 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