Troubleshooting
symptom, cause, fix.

01Where to look first

grep '"type":"error"' data/journal.jsonl | tail -20                 # the last 20 caught errors
grep '"type":"error"' data/journal.jsonl | grep '"agent":"pump"' | tail # one agent: pump, news, analyst, live, whale …

An excerpt that shows the format, with the public RPC, no keys and the optional modules off (times, values and counts are your own):

✅ Hyperliquid info                 … ms  SOL $…
·  HL leaderboard                   … ms  The operation was aborted due to timeout  → `outrider leaders` needs it
✅ Solana RPC                       … ms  slot …
·  Polymarket Gamma                 … ms  fetch failed  → POLYMARKET cannot find markets or settle; POLYMM has no metadata
·  TypeSafe Jev                     … ms  TYPESAFE_API_KEY not set  → Jev is optional — the desk runs without it
✅ pump.fun stream (WS)             … ms  20+ pump.fun log messages — stream healthy
⚠ pump.wsUrl is the public endpoint — it drops heavy streams; get a free Helius/QuickNode WS

All checks passed. (… optional check(s) unavailable.)

Lines with · are optional: services of a module that is off, or keys you have not set. Polymarket is not available from every location, and the large Hyperliquid leaderboard file can time out. Neither stops the memecoin desk. With the module that needs a source switched on, the same failure shows ❌ and counts as failed.

02Solana RPC and WebSocket

Symptoms: no pump.fun events, "pump.fun: not connected" in Telegram /status, the console check "Solana RPC answers" failing, live mode refusing to start.

1. Test the HTTP endpoint

   curl -s -X POST -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' '<your https RPC URL>'

   A healthy endpoint answers {"jsonrpc":"2.0","result":"ok","id":1}. An "error" object usually means a wrong or expired key, or a plan limit: check your provider's dashboard.
2. Test the WebSocketnode src/cli.mjs doctor subscribes to pump.fun logs for up to 12 seconds. 20+ pump.fun log messages — stream healthy is good. connected, but no pump.fun logs arrived means the socket opened but nothing came (provider plan, or a wrong URL). WebSocket error means it could not connect. no global WebSocket — use Node 22+ means your Node is too old.
3. Read the journal

   grep '"agent":"pump"' data/journal.jsonl | grep '"type":"error"' | tail

   ws connect: … = the connection failed; ws stalled — forced reconnect = the socket went quiet and was reopened (normal after a laptop sleeps, worrying if constant); ws: {…} = an error object your provider returned for the subscription.
4. Check which URL is usedThe console field Integrations → Solana RPC URL, when set, replaces solanaRpc and derives pump.wsUrl (http → ws). If your provider's WebSocket address is different, leave the console field empty and set both in config.json (how).
5. Public endpointapi.mainnet-beta.solana.com drops heavy logsSubscribe streams; doctor warns pump.wsUrl is the public endpoint. Use a private endpoint (providers).

03Nothing moves after the laptop slept

A sleeping computer leaves half-open sockets. The pump.fun stream pings every 20 seconds and forces a reconnect when the socket stalls, even if no close event arrives; the journal logs "ws stalled — forced reconnect". Nothing is watched while the machine sleeps, so the paper record has gaps. For a continuous record, run on a server (Deployment).

04Hyperliquid: API wallet and live orders

Live mode does not start. The desk stops with live mode cannot start: followed by one line per problem. The Hyperliquid ones:

Orders are skipped or fail. Read the Live tab, or:

grep '"type":"live_' data/journal.jsonl | tail -20     # live_fill, live_dry, live_skip, live_rebase, live_kill
grep '"agent":"live"' data/journal.jsonl | tail -10     # failed live orders with the exchange's error text

Any other error text in an "agent":"live" row is Hyperliquid's own answer, passed through (for example when the API wallet is not authorised for the account, or the account has no margin). To see what the exchange thinks your account holds:

curl -s -X POST https://api.hyperliquid.xyz/info -H 'content-type: application/json' \
  -d '{"type":"clearinghouseState","user":"<your 0x account address>"}' | head -c 400

If the API wallet was revoked or expired on Hyperliquid, generate and authorise a new one and replace the key (how).

05PumpPortal and live pump.fun orders

Live pump.fun transactions are built by PumpPortal's local-trade API, signed on your machine and sent through your RPC.

06Anthropic API: 401, 429 and billing

Errors from Claude never stop the desk: news falls back to keyword scores and the briefing is skipped. They are written to the journal with "agent":"news" or "agent":"analyst", and the error text starts with the HTTP status:

grep '"type":"error"' data/journal.jsonl | grep -E '"agent":"(news|analyst)"' | tail -5

Test the key outside the desk:

curl -s https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" | head -c 300

No errors and still no briefing? Check that the SDK is installed (npm ls @anthropic-ai/sdk; it is an optional dependency) and that analyst.enabled is on. The first briefing comes after analyst.everyHours. Telegram /brief says "The AI analyst needs an Anthropic API key (console → Integrations)." when no key is set.

07Telegram: token and chat id

• No messages at all. Both TELEGRAM_BOT_TOKEN (or the console field) and TELEGRAM_CHAT_ID must be set; with either missing, alerts only go to the terminal. doctor lists both.
• The terminal shows telegram notify failed: HTTP 401 https://api.telegram.org/bot***/sendMessage: the token is wrong (the token itself is never printed). HTTP 400 …: usually a wrong chat id, or you never pressed Start in the bot's chat.
• Test the token and the chat id directly:

  curl -s "https://api.telegram.org/bot<token>/getMe"
  curl -s "https://api.telegram.org/bot<token>/sendMessage" -d chat_id=<chat id> -d text=test

  "ok":true in both means the desk can send. The console's Integrations page can also test the token (manager or owner), and Status shows "Telegram bot (optional): token is valid when set".
• Alerts arrive, commands are ignored. Commands are answered only in TELEGRAM_CHAT_ID. In a group, also set TELEGRAM_OWNER_ID to your own user id (how). After changing the token in the console, restart the desk: the command listener reads it at start.
• Two desks, one token. Only one program can read a bot's updates at a time. Stop the other one, or give each desk its own bot.

08Install problems and the console database (better-sqlite3)

The console stores its data in data/admin.sqlite through better-sqlite3, a native module. If it did not install for your Node version, the desk prints Admin console failed to start: … with the module's error and runs without the console.

1. Check Nodenode --version must be v22 or higher. After you upgrade Node, reinstall the modules.
2. Check the module

   node -e "const D=require('better-sqlite3'); console.log('better-sqlite3 ok', new D(':memory:').prepare('select sqlite_version() v').get().v)"

   It should print better-sqlite3 ok and a version number.
3. Reinstall

   rm -rf node_modules
   npm ci
   npm run build

   If npm has to compile the module, it needs Python and a C++ compiler: Xcode Command Line Tools on macOS (xcode-select --install), build-essential on Debian/Ubuntu.
4. One desk per data folderTwo processes on the same data/ write over each other's state and compete for the database. Stop the second one.

09Console sign-in behind a reverse proxy

The session cookie is called mk_admin. It is always HttpOnly and SameSite=Strict, and it is marked Secure when the request arrives over HTTPS or carries X-Forwarded-Proto: https. A Secure cookie is only sent back over HTTPS.

Check the cookie flags from the server itself (replace the email and password; the session token in the output is a credential, do not share it):

curl -s -D - -o /dev/null -H 'x-mikodes-admin: 1' -H 'X-Forwarded-Proto: https' \
  -H 'content-type: application/json' -d '{"email":"<email>","password":"<password>"}' \
  http://127.0.0.1:8790/admin/api/auth/login | grep -i set-cookie
# expect: …; HttpOnly; Secure; SameSite=Strict

Without the header the cookie is HttpOnly; SameSite=Strict; with X-Forwarded-Proto: https it is HttpOnly; Secure; SameSite=Strict. Run the same check through your proxy's public address to confirm that the proxy sends the header.

10"cannot be decrypted": the console secret key

• [admin] secret "integrations.…" cannot be decrypted: was the secretKey changed? The key used now is not the one the secret was saved with: ADMIN_SECRET_KEY changed, was added or removed, or data/.admin-secret-key was replaced (for example by copying data/ without it). That feature then behaves as if no key were set.
• [admin] two-factor secret of … cannot be decrypted … The same cause, for authenticator codes. Sign in with a recovery code.
• Admin console failed to start: createAdminKit: secretKey must be 32 bytes as 64 hex chars or base64. Generate one with: openssl rand -hex 32 ADMIN_SECRET_KEY has the wrong format.

Fix: restore the old key and restart; if it is gone, re-enter the secrets. Full steps: Recovery path.

11Rate limits: 429 and timeouts

• Public Solana RPC. fomo, collect and WHALE read transactions one by one; on the public RPC they are slow and get throttled. A private RPC in solanaRpc fixes most of it.
• GeckoTerminal. The free API answers HTTP 429 quickly at about 27 calls a minute (the code comment on gecko.minIntervalMs); the default is one call every 6 seconds. On a 429 the sweep backs off hard and stays slower; the progress line shows "(N× rate-limited)". Leave it running.
• Hyperliquid. The liquidation map paces its reads; if many accounts fail, the summary shows "N failed". Reduce --wallets or the console's accounts-per-refresh.
• HL leaderboard timeout in doctor: the leaderboard file is large; it only affects leaders (perps module) and the liquidation map. Try again later.

12doctor shows a failed source

13The desk does not start

14Dashboard and console

• Sent to /admin all the time: once the owner exists, you must sign in. Sessions last 12 hours.
• 403 "the kill switch needs a manager or owner": viewers can watch but not stop or resume the desk.
• "The setup token is wrong. Use the value of ADMIN_SETUP_TOKEN from the server environment.": paste the exact value from .env (no quotes or spaces). After changing .env, restart the desk.
• "The setup code is wrong. It is printed in the server log.": ADMIN_SETUP_TOKEN is not set, so use a code printed by this install; restart to print a new one.
• The desk refuses to start: "ADMIN_SETUP_TOKEN must be at least 24 characters": use a longer value (openssl rand -hex 24) or leave it empty.
• Too many failed sign-ins: wait 15 minutes.
• Lost two-factor device: sign in with one of your recovery codes instead of the authenticator code. With none left, another owner can remove your account in Team and add it again (you get a new one-time password).
• "restart pending" on the dashboard: you changed Live trading or a Mode involving LIVE while the desk runs. Restart to apply.

15The desk runs but never buys

That is the most common outcome, and usually correct: the EV gate needs expected value of at least 3 % after costs, and the pump.fun filters are strict. Check, in order:

1. What blocks entriesDashboard → Desk control, or /status: kill switch, hard stop, daily loss limit, protections.
2. Modealert mode never trades.
3. RejectionsThe Pump.fun live panel and the Ledger's skip rows show why each candidate was refused.
4. Warningsdoctor lists settings that make entries impossible, for example a minimum stake above the per-token cap.

16Still stuck

See Support. Include the output of node src/cli.mjs doctor and the relevant journal rows, with keys, RPC URLs and wallet keys removed.