> ## Documentation Index
> Fetch the complete documentation index at: https://leadmagic.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for the LeadMagic CLI

Common issues and solutions for the LeadMagic CLI.

## Quick Diagnostics

Run the built-in health check:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm doctor
```

Auto-repair fixable issues:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm doctor --fix
```

Verbose diagnostics:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm doctor --verbose
```

`lm doctor` checks your config file, database, authentication status, and system requirements.

## Debug Logging

Enable detailed logging for any command:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm --debug chat
lm --debug enrich -i contacts.csv
```

Or set the environment variable:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export LM_DEBUG=1
lm chat
```

Debug output includes API requests, tool calls, database queries, and internal state.

## Authentication Issues

> [accordion] Not signed in
>
> **Error:** `Not logged in`, `Authentication required`, or `Session expired`
>
> **Solutions:**
>
> 1. Sign in again:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm login
> ```
>
> 2. Verify the session:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm dashboard
> ```
>
> 3. Run diagnostics:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm doctor
> ```

> [accordion] Session expired
>
> **Error:** `Session expired` or `Token refresh failed`
>
> **Solution:** Sign in again:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm login
> ```
>
> OAuth tokens expire periodically. The CLI attempts automatic refresh, but if that fails, a fresh login is needed.

> [accordion] Login browser doesn't open
>
> **Possible causes:**
>
> * No default browser configured
> * Running in a headless environment (SSH, Docker)
>
> **Solution:** Copy the URL printed in the terminal and open it manually in any browser. After authenticating, the CLI picks up the token automatically.

## Database Issues

> [accordion] Database locked
>
> **Error:** `Database is locked` or `Could not set lock`
>
> **Cause:** Another `lm` process is holding the database lock.
>
> **Solutions:**
>
> 1. Unlock the database:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm db unlock
> ```
>
> Or without confirmation:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm db unlock --yes
> ```
>
> 2. If that doesn't work, check for orphaned processes:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> ps aux | grep lm
> ```

> [accordion] Database corruption
>
> **Error:** `WAL corruption`, `schema mismatch`, or database errors.
>
> **Solutions:**
>
> 1. **Repair** (preserves data when possible):
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm db repair
> ```
>
> 2. **Reset** (destructive — drops all tables):
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm db reset --confirm
> ```
>
> Exported files in `.leadmagic/export/` are not affected by reset.

> [accordion] Database too large
>
> **Solution:** Compact the database to reclaim space:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm db vacuum
> ```
>
> This runs `VACUUM`, updates statistics, and flushes the write-ahead log.

## File and Data Issues

> [accordion] File too large
>
> The CLI enforces row limits for safety:
>
> | Rows | Behavior |
> | - | - |
> | 1–5,000 | Normal processing |
> | 5,001–10,000 | Warning prompt before processing |
> | 10,001+ | Hard stop — file is too large |
>
> **Solutions:**
>
> * Split large files before loading
> * Filter rows using SQL after loading a subset
> * Use the REST API directly for large-scale batch processing

> [accordion] CSV parsing errors
>
> **Common causes:**
>
> * Non-standard delimiters (the CLI auto-detects commas, tabs, semicolons, and pipes)
> * Encoding issues (the CLI handles UTF-8 and BOM)
> * Malformed quotes or escaped characters
>
> **Solutions:**
>
> 1. Try analyzing the file first:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm analyze yourfile.csv
> ```
>
> 2. Check the file encoding — the CLI works best with UTF-8.
> 3. If the file uses an unusual delimiter, the CLI auto-detects it in most cases. If detection fails, pre-process the file to use standard CSV formatting.

> [accordion] Columns not detected
>
> **Cause:** Column names don't match expected patterns (e.g., `email`, `first_name`, `company`).
>
> **Solutions:**
>
> * Specify columns explicitly with `--email-column`, `--first-name-column`, etc. when using `lm enrich`
> * In chat, tell the AI which column contains what: *"The email addresses are in column C"*
> * Run `lm analyze` to see what the CLI detected

## Connection Issues

> [accordion] API request failed
>
> **Possible causes:**
>
> * No internet connection
> * LeadMagic API is temporarily down
> * Your OAuth session is invalid or expired
>
> **Solutions:**
>
> 1. Check your internet connection
> 2. Verify your account session:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm dashboard
> ```
>
> 3. Check the API status at [leadmagic.io/status](https://leadmagic.io/status)

> [accordion] AI chat not responding
>
> **Cause:** The AI Gateway (`ai.leadmagic.io`) may be unreachable.
>
> **Solutions:**
>
> 1. Check you're logged in:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm doctor
> ```
>
> 2. Re-authenticate:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm login
> lm dashboard
> ```
>
> 3. Try with debug logging to see the actual error:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> lm --debug chat
> ```

## Common Error Messages

| Error | Cause | Solution |
| - | - | - |
| `Not logged in` | No local OAuth session | `lm login` |
| `Authentication required` | Command needs an account-backed session | `lm login` |
| `Session expired` | OAuth token expired | `lm login` |
| `Database is locked` | Another process holds the lock | `lm db unlock` |
| `File exceeds row limit` | CSV has >10,000 rows | Split the file or use the API directly |
| `Insufficient credits` | No credits remaining | [Purchase credits](https://app.leadmagic.io/settings/billing) |
| `Command not found: lm` | CLI not in PATH | Open a new terminal or `source ~/.zshrc` |

## Reset Everything

If all else fails, you can reset your entire CLI installation:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm db reset --confirm      # Reset the database
rm ~/.leadmagic/config.json # Remove config (keeps exports)
lm init                    # Re-initialize
lm login                   # Re-authenticate
```

> [!WARNING]
>
> This preserves your exported files in `.leadmagic/export/` but removes all loaded data and configuration.

## Still Need Help?

> [card] [Help Center](https://help.leadmagic.io/en)
>
> Contact support for account or billing issues.

> [card] [API Status](https://leadmagic.io/status)
>
> Check if the LeadMagic API is operational.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.