> ## Documentation Index
> Fetch the complete documentation index at: https://uncoded.ch/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Issues — The Catalog

> The most common problems unCoded operators encounter, and how to fix them. Categorized by symptom for fast lookup.

<Info>
  **Most operator issues fall into a small number of categories.** This page is the catalog — find your symptom, follow the fix. If your issue isn't here, see the more specific [Error Codes](/troubleshooting/error-codes), [Connection Problems](/troubleshooting/connection-problems), or [Escalation](/troubleshooting/escalation) pages.
</Info>

## Issues with the bot not trading

<AccordionGroup>
  <Accordion title="Bot stopped trading suddenly" icon="circle-pause">
    **Most common causes**, in priority order:

    1. **Kill switch is ON.** Most common. Check the Dashboard's main panel. Flip OFF if you intended to be trading.
    2. **Exchange-side outage.** Check the venue's status page. If down, the bot waits for connection.
    3. **Rate limit being hit.** Logs show `429` or `-1003`. Bot auto-cools-down; persistent hits mean over-aggressive configuration.
    4. **Min-notional rejections.** Per-split sizing below exchange floor (Binance: typically `$10`). Increase capital or switch to fewer-split mode.
    5. **Insufficient balance.** Capital was withdrawn or another bot consumed it. Top up or adjust mode's investment-per-buy.
    6. **API key revoked at venue.** Logs show authentication errors. Generate new key, update Dashboard.
    7. **IP allowlist mismatch.** Logs show `-2015` (Binance) or equivalent. Update venue's allowlist to your VPS's current IP.
  </Accordion>

  <Accordion title="Bot trading much more than usual" icon="bolt">
    **Most common causes**:

    1. **SignalEditor strategy with wrong trigger mode.** `once_per_minute` instead of `once_per_bar_close` floods signals.
    2. **New volatility regime.** Mode triggering more buy signals due to faster price movement.
    3. **Newly-added pair without expected characteristics.** New symbol may have very different behavior.
    4. **Configuration drift.** A `canBuy: true` flip happened that shouldn't have.

    **Fix**: investigate the trigger frequency in Logs. Identify which pair/mode is over-trading. Adjust trigger mode or pause the over-trading pair.
  </Accordion>

  <Accordion title="Bot trading but never closing positions" icon="hourglass">
    **Most common causes**:

    1. **Sell ladder rungs too far above entry.** If price hasn't recovered to the first sell rung, position stays open.
    2. **Mode's `canSell: false`** — was set somewhere, prevents sell-side activity.
    3. **Stop-loss disabled and price has fallen substantially.** Without a stop, no automatic exit.
    4. **Position is held in a regime mismatch** — buy ladder fully invested, price below all sell rungs.

    **Fix**: review per-pair positions in Live Trades panel. Decide manually whether to close, hold, or wait. Re-engage `canSell: true` if accidentally disabled.
  </Accordion>

  <Accordion title="Bot placing orders at unexpected prices" icon="circle-question">
    **Most common causes**:

    1. **Mode parameters changed without your awareness.** Verify in Modes panel.
    2. **Multiple modes fighting over the same pair.** Should be single-mode-per-pair.
    3. **Symbol's tick precision differs from expectation.** Bot rounds to venue's lot/tick rules.
    4. **Stale configuration from incomplete update.** Restart container.

    **Fix**: Modes panel review, configuration verification, container restart.
  </Accordion>
</AccordionGroup>

## Issues with the Dashboard

<AccordionGroup>
  <Accordion title="Can't log into the Dashboard" icon="key">
    **Most common causes**:

    1. **Wrong password.** Try the password from your password manager. If you've forgotten it, reset via the SSH-level configuration.
    2. **Browser cookies/cache.** Clear cookies for the dashboard domain, retry.
    3. **TLS / certificate expired.** Browser warns about HTTPS issue. Renew Let's Encrypt cert (if Caddy, this should auto-renew).
    4. **IP allowlist at reverse proxy.** If you've allowlisted IPs, verify your current IP is on the list.

    **Fix**: try simpler causes first; rarely need to involve VPS-level recovery.
  </Accordion>

  <Accordion title="Dashboard shows stale data" icon="clock">
    **Most common causes**:

    1. **Database connection issue.** Dashboard reads from database; if connection broken, displays last cache.
    2. **Dashboard container needs restart.** `docker-compose restart dashboard`.
    3. **Browser cached old state.** Refresh the page, then hard-refresh (Ctrl+Shift+R).
  </Accordion>

  <Accordion title="Logs panel not streaming" icon="terminal">
    **Most common causes**:

    1. **Browser blocking server-sent events.** Try a different browser.
    2. **Dashboard container's host-Docker-socket access broken.** Check container deployment configuration.
    3. **TradingBot container not running.** Logs panel needs an active container to stream from.
  </Accordion>

  <Accordion title="Tax Report export fails" icon="file-invoice">
    **Most common causes**:

    1. **Frankfurter API unreachable.** Currency conversion depends on it. Retry later.
    2. **Date range too large.** Try smaller chunks (one month at a time).
    3. **Database query timeout for very long histories.** Run during quieter operational hours.
  </Accordion>
</AccordionGroup>

## Issues with notifications

<AccordionGroup>
  <Accordion title="Telegram notifications stopped" icon="paper-plane">
    **Most common causes**:

    1. **TelegramBot container not running.** Restart it.
    2. **Telegram bot token expired/revoked.** Generate new token via BotFather; update environment variable.
    3. **Chat ID changed.** Verify chat ID matches the configured value.
    4. **Telegram API outage.** Check Telegram's status; usually resolves quickly.
    5. **Database has no new closed trades.** Bot is doing nothing to notify about. Verify TradingBot is running.
  </Accordion>

  <Accordion title="Telegram running total disagrees with Dashboard" icon="balance-scale">
    **Most common causes**:

    1. **Bot was offline during a trade.** Telegram missed it; database has it.
    2. **Database restored from backup.** Running total reset.
    3. **Manual close not reflected in one of the surfaces.**

    **Fix**: Dashboard's analytics are the source of truth. Telegram running total is for convenience.
  </Accordion>
</AccordionGroup>

## Issues with strategies

<AccordionGroup>
  <Accordion title="SignalEditor strategy never fires" icon="ban">
    **Most common causes**:

    1. **Strategy not started.** Hit "Start" in the SignalEditor.
    2. **Trigger mode is `once`** — fires only once per strategy lifetime. Restart the strategy to reset.
    3. **Conditions too tight.** Preview shows zero signals. Loosen thresholds.
    4. **SignalEditor scheduler not running.** Verify SignalEditor container is up.
    5. **Webhook URL is misconfigured.** SignalEditor fires but SignalsBot doesn't receive.
  </Accordion>

  <Accordion title="SignalEditor strategy fires too often" icon="bolt">
    **Most common causes**:

    1. **Trigger mode `once_per_minute` instead of `once_per_bar_close`.** Switch the trigger.
    2. **Conditions too loose.** Tighten thresholds.
    3. **No trend filter on a mean-reversion strategy.** Add EMA-filter condition.
  </Accordion>

  <Accordion title="SignalEditor preview differs from live" icon="circle-question">
    **Most common causes**:

    1. **Live data differs slightly from historical (real-time vs cached).**
    2. **Custom indicator computation has subtle look-ahead bias** in preview that's not present in live.
    3. **Latency causes live to evaluate differently than preview.**

    **Fix**: contact support for investigation. Preview-equals-live is a design goal; deviations are bugs.
  </Accordion>
</AccordionGroup>

## Issues with backtesting

<AccordionGroup>
  <Accordion title="Backtest stuck or fails" icon="hourglass">
    **Most common causes**:

    1. **Workers occupied.** Backtester has concurrency cap; queued backtests wait.
    2. **Symbol historical data not yet imported.** First backtest of a symbol triggers data fetch from venue.
    3. **Date range too large for the engine.** Try smaller windows.
    4. **Strategy JSON is malformed.** Validate the JSON before submitting.

    **Fix**: wait, retry with smaller window, validate JSON.
  </Accordion>

  <Accordion title="Backtest results look unrealistic" icon="circle-exclamation">
    **Most common causes**:

    1. **Look-ahead bias in custom strategy.** Indicator computed with future data leakage.
    2. **Fee or slippage assumption too low.** Update parameters.
    3. **Survivorship bias on long-tail altcoins.**
    4. **Curve-fitting to a single window.** Validate on multiple windows.

    See [Backtesting Common Mistakes](/backtesting/common-mistakes) for the full catalog.
  </Accordion>
</AccordionGroup>

## Issues with venue connectivity

See [Connection Problems](/troubleshooting/connection-problems) for the dedicated guide.

<AccordionGroup>
  <Accordion title="Brief summary" icon="wifi">
    * **Connection drops**: usually transient. Bot auto-reconnects. Reconciliation handles missed events.
    * **IP allowlist mismatch**: most common cause of authentication failures. Verify VPS IP matches venue's allowlist.
    * **API key revoked**: regenerate at the venue, update Dashboard, restart bot.
    * **Exchange outage**: check the venue's status page. Wait through. Bot resumes when venue returns.
  </Accordion>
</AccordionGroup>

## Issues with VPS / infrastructure

<AccordionGroup>
  <Accordion title="VPS running out of disk space" icon="hard-drive">
    **Most common causes**:

    1. **Logs filling up disk.** Configure log rotation (most operators inherit from default Docker config).
    2. **Database growing without bound.** Periodically purge old data if you're storing more than your retention policy needs.
    3. **Backups stored locally instead of off-site.** Move backups to off-site storage.

    **Fix**: log rotation, database vacuum, off-site backups.
  </Accordion>

  <Accordion title="VPS network slow / unstable" icon="wifi">
    **Most common causes**:

    1. **Provider network issue.** Status page check.
    2. **Geographic distance to exchange.** If you're a US operator on EU VPS trading Binance, latency is higher than necessary.
    3. **VPS provider over-subscription** — your "shared" VPS is contended.

    **Fix**: try a different provider/region, check provider status.
  </Accordion>

  <Accordion title="Container restart loops" icon="rotate">
    **Most common causes**:

    1. **Configuration error.** Check logs immediately on restart attempts.
    2. **Database connection issue.** Ensure database container started before depending containers.
    3. **Out of memory.** Larger backtests or many active strategies can exceed memory budget.
    4. **Recent update incompatibility.** Roll back if needed.

    **Fix**: read the logs, address the root cause, restart.
  </Accordion>
</AccordionGroup>

## When to engage the kill switch during troubleshooting

<Tip>
  **If you're investigating an unfamiliar issue and want to remove "still trading" from the variables**: kill switch ON.

  The bot pauses new buying. Existing positions continue managing. You investigate without ongoing risk. Re-enable when you're confident the issue is resolved.

  False alarms are free; real alarms are real.
</Tip>

## Best practices for troubleshooting

<Tip>
  * ✅ **Read the logs first** — Dashboard's Logs panel surfaces most issues with clear messages.
  * ✅ **Try simple causes first** — restart, kill switch, refresh, before deeper investigation.
  * ✅ **Engage kill switch when investigating** — removes one variable from the situation.
  * ✅ **Document each incident** in your operator log — pattern recognition helps future you.
  * ✅ **Don't make multiple changes simultaneously** — change one variable at a time during diagnosis.
  * ✅ **Cross-reference with documentation** — most issues are documented somewhere.
  * ✅ **Use the operator community** — many issues have been encountered before.
  * ✅ **Escalate to support** when documentation and community don't resolve.
  * ✅ **Don't panic-close positions** during stress — patience usually serves better.
  * ✅ **Maintain backups** — you might need them.
</Tip>

## What's next

<CardGroup cols={2}>
  <Card title="Error codes" icon="bug" href="/troubleshooting/error-codes">
    Per-venue error code reference.
  </Card>

  <Card title="Connection problems" icon="wifi" href="/troubleshooting/connection-problems">
    Connectivity-specific troubleshooting.
  </Card>

  <Card title="Escalation" icon="forward" href="/troubleshooting/escalation">
    When and how to escalate.
  </Card>

  <Card title="Support" icon="life-ring" href="/operations/support">
    Reaching out for help.
  </Card>

  <Card title="Daily operations" icon="calendar-day" href="/operations/daily-operations">
    Routines that catch issues early.
  </Card>

  <Card title="Monitoring" icon="heart-pulse" href="/operations/monitoring">
    Spotting problems before they're crises.
  </Card>
</CardGroup>