> ## 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

<AccordionGroup>
  <Accordion title="Not signed in" icon="key">
    **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>

  <Accordion title="Session expired" icon="clock">
    **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>

  <Accordion title="Login browser doesn't open" icon="globe">
    **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.
  </Accordion>
</AccordionGroup>

## Database Issues

<AccordionGroup>
  <Accordion title="Database locked" icon="lock">
    **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>

  <Accordion title="Database corruption" icon="triangle-exclamation">
    **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>

  <Accordion title="Database too large" icon="hard-drive">
    **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.
  </Accordion>
</AccordionGroup>

## File and Data Issues

<AccordionGroup>
  <Accordion title="File too large" icon="file-exclamation">
    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>

  <Accordion title="CSV parsing errors" icon="file-csv">
    **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>

  <Accordion title="Columns not detected" icon="table-columns">
    **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
  </Accordion>
</AccordionGroup>

## Connection Issues

<AccordionGroup>
  <Accordion title="API request failed" icon="wifi">
    **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>

  <Accordion title="AI chat not responding" icon="robot">
    **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
    ```
  </Accordion>
</AccordionGroup>

## 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.
</Warning>

## Still Need Help?

<CardGroup cols={2}>
  <Card title="Help Center" icon="life-ring" href="https://help.leadmagic.io/en">
    Contact support for account or billing issues.
  </Card>

  <Card title="API Status" icon="signal" href="https://leadmagic.io/status">
    Check if the LeadMagic API is operational.
  </Card>
</CardGroup>