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:

lm doctor

Auto-repair fixable issues:

lm doctor --fix

Verbose diagnostics:

lm doctor --verbose

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

Debug Logging

Enable detailed logging for any command:

lm --debug chat
lm --debug enrich -i contacts.csv

Or set the environment variable:

export LM_DEBUG=1
lm chat

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

Authentication Issues

Not signed in

Error: Not logged in, Authentication required, or Session expired

Solutions:

1. Sign in again:

lm login

2. Verify the session:

lm dashboard

3. Run diagnostics:

lm doctor

Session expired

Error: Session expired or Token refresh failed

Solution: Sign in again:

lm login

OAuth tokens expire periodically. The CLI attempts automatic refresh, but if that fails, a fresh login is needed.

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

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:

lm db unlock

Or without confirmation:

lm db unlock --yes

2. If that doesn’t work, check for orphaned processes:

ps aux | grep lm

Database corruption

Error: WAL corruption, schema mismatch, or database errors.

Solutions:

1. Repair (preserves data when possible):

lm db repair

2. Reset (destructive — drops all tables):

lm db reset --confirm

Exported files in .leadmagic/export/ are not affected by reset.

Database too large

Solution: Compact the database to reclaim space:

lm db vacuum

This runs VACUUM, updates statistics, and flushes the write-ahead log.

File and Data Issues

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

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:

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.

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

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:

lm dashboard

3. Check the API status at leadmagic.io/status

AI chat not responding

Cause: The AI Gateway (ai.leadmagic.io) may be unreachable.

Solutions:

1. Check you’re logged in:

lm doctor

2. Re-authenticate:

lm login
lm dashboard

3. Try with debug logging to see the actual error:

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

lm db reset --confirm      # Reset the database
rm ~/.leadmagic/config.json # Remove config (keeps exports)
lm init                    # Re-initialize
lm login                   # Re-authenticate

This preserves your exported files in .leadmagic/export/ but removes all loaded data and configuration.

Still Need Help?

Help Center

Contact support for account or billing issues.

API Status

Check if the LeadMagic API is operational.