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:
- Verify credentials work at https://app.monarchmoney.com
- Check for typos in environment variables
- 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:
-
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)
-
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:
-
Sync system clock:
# macOS/Linux sudo ntpdate -s time.apple.com # Check current time date -
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:
- Check transaction/category IDs are valid UUIDs
- Verify required fields are provided
- 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:
- Wait and retry
- Check https://status.monarchmoney.com for outages
- Try with a smaller request (fewer transactions)
525 SSL Handshake Failed
Cause: Cloudflare protection or network issue.
Solutions:
- Wait 1-2 minutes and retry
- Check your network connection
- 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:
-
Install globally:
npm install -g monarch-money -
Or use npx:
npx monarch-money doctor -
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