Having trouble? This guide covers the most common issues and their solutions.

## Browser issues

### Chrome not detected

**Symptoms:** App says Chrome isn't installed or can't find your browser.

**Solutions:**

1. Ensure Google Chrome is installed in your Applications folder  
2. Launch Chrome at least once to create the profile directory  
3. Restart The Password App

### Browser automation fails

**Symptoms:** The AI can't control the browser or pages don't load.

**Solutions:**

1. Close all Chrome windows before starting a password change  
2. Check that no other automation tools are running  
3. Try clearing Chrome's cache and restarting  
4. Ensure you have a stable internet connection

### Anti-bot detection triggered

**Symptoms:** Website shows CAPTCHA or blocks the automation.

**Solutions:**

1. Some sites have aggressive bot detection that may require manual completion  
2. Try changing the password at a different time  
3. For persistent issues, you may need to change that password manually

## API issues

If you see any API-related errors (invalid key, rate limiting, insufficient credits), please contact us at [contact@thepassword.app](mailto:contact@thepassword.app) and we'll resolve it for you.

API access is managed automatically by The Password App - you don't need to configure any API keys yourself.

## Password change failures

### Site not supported

**Symptoms:** AI can't find the password change form or navigate the site.

**Solutions:**

1. Some sites have unusual layouts that confuse the AI  
2. Check if the site requires a specific login flow  
3. Try the password change manually for that site  
4. Report the issue to us so we can improve support

### Two-factor authentication issues

**Symptoms:** Password change stops at 2FA step.

**Solutions:**

1. For email 2FA, ensure your email is accessible in the browser  
2. For SMS, you may need to enter the code manually when prompted  
3. For authenticator apps, enter the code when the app prompts you

### Session expired

**Symptoms:** AI starts but then shows a login page.

**Solutions:**

1. Log in to the website manually in Chrome first  
2. Ensure "stay logged in" or "remember me" is checked  
3. Clear Chrome cookies and log in again

### Network timeout

**Symptoms:** Password change times out or fails to load pages.

**Solutions:**

1. Check your internet connection  
2. Some sites may be temporarily slow or down  
3. Try again in a few minutes

## App crashes

### App won't launch on macOS

**Symptoms:** App crashes immediately or shows a security error.

**Solutions:**

1. **Gatekeeper block:** Right-click the app and select "Open" instead of double-clicking  
2. **M1/M2/M3 Macs:** Ensure you downloaded the correct version for Apple Silicon  
3. **Corrupted download:** Delete the app and re-download from our website

### App crashes during password change

**Symptoms:** App quits unexpectedly while changing a password.

**Solutions:**

1. Check the logs at `~/Library/Application Support/password-manager-pro/logs/`  
2. Ensure you have enough disk space (at least 1GB free)  
3. Try restarting your Mac  
4. Update to the latest version of the app

### Blank screen or UI not loading

**Symptoms:** App opens but shows a blank or partially loaded interface.

**Solutions:**

1. Wait a few seconds for the UI to fully load  
2. Try resizing the window  
3. Delete app preferences: `rm -rf ~/Library/Application Support/password-manager-pro/`  
4. Re-download and reinstall the app

## Getting more help

### Check the logs

Application logs can help diagnose issues:

```
~/Library/Application Support/password-manager-pro/logs/main-YYYY-MM-DD.log
```

Review recent log entries for error messages.

### Contact support

If you can't resolve an issue:

1. Email us at [contact@thepassword.app](mailto:contact@thepassword.app)  
2. Include:
   - Your macOS version  
   - The Password App version (from Settings)  
   - Description of the issue  
   - Any error messages you see

### Report a bug

Found a bug? Help us improve:

1. Email [contact@thepassword.app](mailto:contact@thepassword.app) with "Bug Report" in the subject  
2. Describe what you expected vs. what happened  
3. Include steps to reproduce if possible

We typically respond within 24-48 hours.