Skip to main content
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, API key, 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

Error: LeadMagic API key not foundSolutions:
  1. Set your API key:
lm config set apiKey
  1. Or use an environment variable:
export LEADMAGIC_API_KEY="lm_your_key_here"
  1. Verify it’s set:
lm config get apiKey
Get your key from Settings > API.
Error: Session expired or Token refresh failedSolution: Sign in again:
lm login
OAuth tokens expire periodically. The CLI attempts automatic refresh, but if that fails, a fresh login is needed.
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

Error: Database is locked or Could not set lockCause: Another lm process is holding the database lock.Solutions:
  1. Unlock the database:
lm db unlock
Or without confirmation:
lm db unlock --yes
  1. If that doesn’t work, check for orphaned processes:
ps aux | grep lm
Error: WAL corruption, schema mismatch, or database errors.Solutions:
  1. Repair (preserves data when possible):
lm db repair
  1. Reset (destructive — drops all tables):
lm db reset --confirm
Exported files in .leadmagic/export/ are not affected by reset.
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

The CLI enforces row limits for safety:
RowsBehavior
1–5,000Normal processing
5,001–10,000Warning 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
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
  1. Check the file encoding — the CLI works best with UTF-8.
  2. 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.
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

Possible causes:
  • No internet connection
  • LeadMagic API is temporarily down
  • API key is invalid or expired
Solutions:
  1. Check your internet connection
  2. Verify your API key:
lm dashboard
  1. Check the API status at leadmagic.io/status
Cause: The AI Gateway (ai.leadmagic.io) may be unreachable.Solutions:
  1. Check you’re logged in:
lm doctor
  1. Re-authenticate:
lm login
lm config set apiKey
  1. Try with debug logging to see the actual error:
lm --debug chat

​
Common Error Messages

ErrorCauseSolution
API key not foundNo key configuredlm config set apiKey
Session expiredOAuth token expiredlm login
Database is lockedAnother process holds the locklm db unlock
File exceeds row limitCSV has >10,000 rowsSplit the file or use the API directly
Insufficient creditsNo credits remainingPurchase credits
Command not found: lmCLI not in PATHOpen 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
lm config set apiKey       # Re-set API key
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.