Files

4.8 KiB

Troubleshooting Guide

Table of Contents

Authentication Issues

"Not logged in" Error

Cause: No valid session exists.

Solution:

monarch-money auth login

"Invalid credentials" Error

Cause: Email or password is incorrect.

Solutions:

  1. Verify credentials work at https://app.monarchmoney.com
  2. Check for typos in environment variables
  3. Ensure password doesn't contain shell special characters (use quotes)
export MONARCH_PASSWORD='pa$$word!with@special#chars'

"Authentication failed" After Working Previously

Cause: Session expired or Monarch Money invalidated it.

Solution:

monarch-money auth logout
monarch-money auth login

MFA Problems

"MFA code required" Error

Cause: MONARCH_MFA_SECRET not set or invalid.

Solutions:

  1. Get your MFA secret:

    • Login to https://app.monarchmoney.com
    • Settings > Security > Two-Factor Authentication
    • Disable and re-enable MFA
    • Click "Can't scan? View setup key"
    • Copy the base32 string (like JBSWY3DPEHPK3PXP)
  2. Set the variable:

    export MONARCH_MFA_SECRET="YOUR_SECRET_HERE"
    

"MFA code expired" or "Invalid MFA code"

Cause: System clock is out of sync. TOTP codes are time-sensitive (30-second windows).

Solutions:

  1. Sync system clock:

    # macOS/Linux
    sudo ntpdate -s time.apple.com
    
    # Check current time
    date
    
  2. Verify the secret is correct:

    • The secret should be a base32 string (letters A-Z and numbers 2-7)
    • It should NOT be the 6-digit code from your authenticator app
    • Example valid secret: JBSWY3DPEHPK3PXP

MFA Secret vs MFA Code

Item Format Example Use
MFA Secret Base32 string JBSWY3DPEHPK3PXP Set as MONARCH_MFA_SECRET
MFA Code 6 digits 123456 Entered manually in apps

The CLI needs the secret to generate codes automatically. If you only have the 6-digit code, you need to regenerate MFA in Monarch Money settings.

API Errors

400 Bad Request

Cause: Invalid query or mutation.

Solutions:

  1. Check transaction/category IDs are valid UUIDs
  2. Verify required fields are provided
  3. Check amount formats (negative for expenses)

401 Unauthorized

Cause: Session token invalid or expired.

Solution:

monarch-money auth logout
monarch-money auth login

429 Too Many Requests

Cause: Rate limit exceeded.

Solution: Wait and retry. The client has built-in rate limiting, but rapid scripted calls may still hit limits.

500 Internal Server Error

Cause: Monarch Money API issue.

Solutions:

  1. Wait and retry
  2. Check https://status.monarchmoney.com for outages
  3. Try with a smaller request (fewer transactions)

525 SSL Handshake Failed

Cause: Cloudflare protection or network issue.

Solutions:

  1. Wait 1-2 minutes and retry
  2. Check your network connection
  3. Try from a different network

Session Issues

Session File Location

Sessions are stored at: ~/.mm/session.json

Corrupt Session File

Symptoms: Unexpected errors, partial logins

Solution:

# Remove session file
rm ~/.mm/session.json

# Re-authenticate
monarch-money auth login

Permission Errors

Cause: Session directory has wrong permissions.

Solution:

chmod 700 ~/.mm
chmod 600 ~/.mm/session.json

CLI Problems

"command not found: monarch-money"

Cause: CLI not installed or not in PATH.

Solutions:

  1. Install globally:

    npm install -g monarch-money
    
  2. Or use npx:

    npx monarch-money doctor
    
  3. Check npm bin directory is in PATH:

    npm bin -g
    # Add this path to your shell profile
    

Node.js Version Error

Cause: Node.js < 18

Solution:

# Check version
node --version

# Install Node 18+ using nvm
nvm install 18
nvm use 18

JSON Output Not Parsing

Cause: Error messages mixing with JSON output.

Solution: Errors go to stderr, JSON to stdout. Capture separately:

monarch-money tx list --limit 5 2>/dev/null | jq .

Diagnostic Commands

Full System Check

monarch-money doctor

Check Environment Variables

echo "Email: ${MONARCH_EMAIL:-(not set)}"
echo "Password: ${MONARCH_PASSWORD:+set}"
echo "MFA: ${MONARCH_MFA_SECRET:+set}"

Test API Connectivity

curl -s -o /dev/null -w "%{http_code}" https://api.monarch.com/graphql
# Should return 401 (requires auth) not 5xx (server error)

Verbose Logging

Set debug environment variable for more output:

DEBUG=monarch* monarch-money tx list --limit 1