dextermdocs › Troubleshooting
Troubleshooting
What each doctor line and in-app message means, and the fix.
dexterm doctor is the first stop. It exits 0 when the app will run (warnings are optional) and 1 when something must be fixed, and every non-pass line prints the exact fix.
Doctor lines#
| line | meaning | fix |
|---|---|---|
✗ Node … too old | Node is below 22.18 (needed to run the TypeScript entry) | nvm install 22 or brew install node, then re-run. ./install.sh can fetch a verified Node for you. |
! Terminal: not a TTY | output is piped or the shell is not interactive | run dexterm in a terminal window. One-shot frames still work with --screen. |
! Terminal colour: 256-colour only | the terminal cannot do 24-bit colour | use a truecolor terminal (iTerm2, WezTerm, Ghostty, Kitty, Alacritty, Windows Terminal) or set COLORTERM=truecolor. The app runs, flattened. |
! Terminal colour: no colour | NO_COLOR is set, or a monochrome terminal | unset NO_COLOR for the full look; dexterm works in monochrome. |
! Claude CLI: not found | claude is not on PATH | only the analyst needs it: install Claude Code and run claude once to log in. Everything else works. |
! Helius RPC: no key | no key configured | optional. Holders and some safety fields show needs key; see configuration. |
✗ Data sources: unreachable … | a required host did not answer | check your connection, VPN or firewall. If only some hosts fail they may be blocked on your network. --fixtures or DEXTERM_OFFLINE=1 browse offline demo data. |
! Data sources: … PumpPortal … | only the new-pairs host is down | the rest works; new pairs may be blocked on your network. |
! Chart window: not built | no native shell | the chart popup opens in your browser. For the docked window install Rust and run npm run build:shell in packages/popup. |
✗ Data directory: cannot write … | the data dir is not writable | fix the permissions the line names, or run with --db :memory:. |
In-app messages#
| message | meaning |
|---|---|
connecting to the live feed… | the first DexScreener list has not landed yet; skeleton rows show in the meantime |
offline — can't reach the data feed | no source answered; run dexterm doctor. r retries. |
rate-limited — backing off | a source returned 429; the limiter pauses it (30 s, doubling to 10 min) and other sources keep going |
unavailable: <reason> / needs key in a panel | that panel's source is down or needs a key; nothing is fabricated |
cached Nm old · refreshing | the screener painted its last snapshot while fresh rows load |
claude is not logged in in the analyst panel | run claude login and retry |
analyst busy; Esc to interrupt before vetting | one run per conversation at a time; esc interrupts it |
open links needs live mode / paper trading needs live mode | fixtures and one-shot frames have no real links or quotes |
AI scan needs live data (or --replay FILE) | the scan has nothing real to watch on fixtures |
AI scan blocked analyst action "…" · observe-only | the model tried an action during a scan and the app refused it; this is the safety layer working |
rate limited by Jupiter — retrying… on a ticket | the keyless quote bucket is paused; the confirm retries for up to 8 s, then lets you retry or cancel |
chart opened in browser (<reason>) | the native shell is not built or has no display; the page says why too |
Common questions#
The screener is empty on first launch. It should paint cached or skeleton rows within a second. If it stays empty for more than a few seconds, run dexterm doctor: the Jupiter bucket allows one call every ~3 s keyless, and a 429 pauses it for 30 s.
Candles load slowly after switching timeframe. 5m/15m derive from 1m and 4h/1d from 1h locally, so a switch costs at most one fetch, and the chart goes ahead of background work. GeckoTerminal allows about 10 calls a minute per IP; several dexterm instances on one IP share that.
The chart popup did not dock. macOS Automation permission was denied, or the terminal is not Terminal.app or iTerm2; the window opens at the screen edge instead. Drag it where you want it.
Quitting takes long. It should take under a second. If it does not, report it with --verbose output; the shutdown signal cancels every pending wait.
Something that looks like dexterm asks for a seed phrase or a wallet connection. It is not dexterm. The app never asks for keys; see security and trust.
Reporting a problem#
Include dexterm --version, the dexterm doctor output (it contains no secrets), your terminal, and if possible a --record file of the one-shot frame that misbehaves (keys are redacted at capture). Where to send it is on the trust page.