> ## 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.

# Connection Problems — Diagnosing Connectivity

> When the bot can't reach the exchange, the database, or the dashboard. Symptoms, causes, and fixes for connectivity issues.

<Info>
  **Connection problems are usually transient and self-resolving.** The bot reconnects automatically; reconciliation handles missed events. But persistent or severe connection issues need operator attention. This page is the connectivity-specific troubleshooting guide.
</Info>

## Connection layers — what can fail

<CardGroup cols={2}>
  <Card title="Bot → Exchange (REST API)" icon="globe">
    Outbound HTTPS calls to place orders, query balances, fetch market data.
  </Card>

  <Card title="Bot → Exchange (WebSocket)" icon="bolt">
    Outbound persistent connection for real-time fills and market data.
  </Card>

  <Card title="Bot → Database" icon="database">
    Internal Docker network connection to the local PostgreSQL.
  </Card>

  <Card title="Browser → Dashboard" icon="window-maximize">
    Inbound HTTPS connection (through your reverse proxy) for operator access.
  </Card>

  <Card title="External → SignalsBot" icon="rss">
    Inbound HTTPS connection (through your reverse proxy) for webhook delivery.
  </Card>

  <Card title="Bot → External APIs" icon="cloud">
    Outbound to Telegram (notifications), Frankfurter (FX rates), license verification.
  </Card>
</CardGroup>

## Bot → exchange (REST + WebSocket)

<AccordionGroup>
  <Accordion title="Symptoms" icon="circle-question">
    * Logs show authentication errors (`-2015`, `10003`, `EAPI:Invalid key`).
    * Logs show connection-refused or timeout errors.
    * Dashboard shows "exchange disconnected" status.
    * WebSocket repeatedly reconnects.
  </Accordion>

  <Accordion title="Cause: IP allowlist mismatch" icon="shield">
    Most common cause. Your VPS's actual public IP differs from the IP on the exchange's API key allowlist.

    **Fix**:

    1. From VPS: `curl -s https://api.ipify.org`.
    2. Compare to API key's allowlist at the venue.
    3. If different: update the venue's allowlist.
    4. Wait `30–60` seconds for propagation.
    5. Verify connection.

    **Common scenarios that change VPS IP**:

    * Provider migration.
    * VPS rebuild/reinstall.
    * IPv6 transition.
    * Some providers' "snapshot restore" assigns new IP.
  </Accordion>

  <Accordion title="Cause: Exchange-side outage" icon="cloud-bolt">
    Venue is down or having issues.

    **Fix**:

    1. Check venue's status page (most have one).
    2. If exchange is down: wait through. Bot will reconnect when it returns.
    3. Existing exchange-side orders continue honoring during outage.
    4. Verify reconciliation matches expectation when venue returns.
  </Accordion>

  <Accordion title="Cause: VPS network issue" icon="wifi">
    Your VPS can't reach the exchange.

    **Diagnose**:

    * From VPS: `ping api.binance.com` (or relevant venue host).
    * From VPS: `curl https://api.binance.com/api/v3/ping`.
    * If timeouts: VPS network issue.
    * Check provider status page.

    **Fix**:

    * VPS provider issue: wait or contact provider.
    * Routing issue: rare, but can affect specific operators.
  </Accordion>

  <Accordion title="Cause: API key revoked or expired" icon="key">
    Authentication failure with valid-looking key.

    **Fix**:

    1. Verify the key still exists at the venue's API management page.
    2. If revoked: generate new key with same permissions.
    3. Update Dashboard with new credentials.
    4. Restart TradingBot container.
  </Accordion>

  <Accordion title="Cause: clock drift" icon="clock">
    VPS clock differs from exchange's clock by more than `recvWindow` (Binance: `60000` ms).

    **Symptom**: timestamp errors (`-1021` on Binance).

    **Fix**:

    * Check NTP: `timedatectl status` should show synchronized.
    * If not, install/start NTP service.
    * Don't reduce `recvWindow` below default to "fix" — fix the clock instead.
  </Accordion>
</AccordionGroup>

## Bot → database

<AccordionGroup>
  <Accordion title="Symptoms" icon="circle-question">
    * Logs show "could not connect to database" or similar.
    * Dashboard shows stale data.
    * All bot containers show database-related errors.
  </Accordion>

  <Accordion title="Cause: database container not running" icon="database">
    The PostgreSQL container is down.

    **Fix**:

    1. `docker ps` to see what's running.
    2. If database container is missing/stopped: `docker-compose up -d postgres` (or equivalent).
    3. Verify it starts cleanly: `docker logs <db-container>`.
  </Accordion>

  <Accordion title="Cause: wrong credentials in environment" icon="key">
    Configuration drift after an update or restart.

    **Fix**:

    * Verify environment variables (`POSTGRES_USER`, `POSTGRES_PASSWORD`, etc.) match between database container and dependent containers.
    * Restart all containers after environment changes.
  </Accordion>

  <Accordion title="Cause: database disk full" icon="hard-drive">
    PostgreSQL refuses connections when out of disk space.

    **Fix**:

    1. Check disk: `df -h`.
    2. If full: clean up logs, old backups, anything safe to delete.
    3. Consider growing the disk via your VPS provider.
    4. Restart database container after freeing space.
  </Accordion>

  <Accordion title="Cause: database corruption" icon="explosion">
    Rare but possible after improper shutdown or hardware fault.

    **Fix**:

    * Severe situation. Restore from your most recent backup.
    * Spin up fresh PostgreSQL container, restore database, reconnect.
    * Trade history since last backup is lost (or recoverable from venue data).
  </Accordion>
</AccordionGroup>

## Browser → Dashboard

<AccordionGroup>
  <Accordion title="Symptoms" icon="circle-question">
    * Browser shows "can't reach this page" or TLS errors.
    * Dashboard URL times out.
    * Reverse proxy shows `502 Bad Gateway`.
  </Accordion>

  <Accordion title="Cause: Dashboard container not running" icon="server">
    The Dashboard container has stopped.

    **Fix**:

    1. `docker ps`.
    2. If container missing/stopped: `docker-compose up -d dashboard`.
    3. Check logs: `docker logs <dashboard-container>`.
  </Accordion>

  <Accordion title="Cause: TLS certificate expired" icon="lock">
    Let's Encrypt certificate didn't renew. Browser shows insecure-connection warning.

    **Fix**:

    * Caddy auto-renews. If it's failed, check Caddy logs for errors (DNS, ports blocked, rate-limit hit).
    * Manually trigger renewal if needed.
    * Verify port `80` and `443` are open for the renewal challenge.
  </Accordion>

  <Accordion title="Cause: reverse proxy misconfigured or down" icon="route">
    The proxy isn't routing to the Dashboard correctly.

    **Fix**:

    * Verify proxy is running.
    * Check proxy logs.
    * Verify upstream (Dashboard container) is reachable from proxy.
    * Test `curl http://<dashboard-internal-ip>:<port>` from the VPS to confirm Dashboard responds.
  </Accordion>

  <Accordion title="Cause: IP allowlist at proxy excludes you" icon="filter">
    If you've configured proxy-level IP allowlisting and your IP changed.

    **Fix**:

    * Update proxy allowlist with your new IP.
    * Verify by accessing from the previously-allowed location.
  </Accordion>
</AccordionGroup>

## External → SignalsBot

<AccordionGroup>
  <Accordion title="Symptoms" icon="circle-question">
    * TradingView alerts fire but configuration doesn't change.
    * SignalEditor strategies fire but TradingBot doesn't pick up the change.
    * SignalsBot logs show no incoming webhooks.
  </Accordion>

  <Accordion title="Cause: SignalsBot container not running" icon="server">
    Same fix pattern as Dashboard. Verify container, check logs, restart.
  </Accordion>

  <Accordion title="Cause: Reverse proxy not routing to SignalsBot" icon="route">
    Verify proxy configuration includes the SignalsBot's domain.

    Test: `curl https://signals.yourdomain.com/health`. Should return OK.
  </Accordion>

  <Accordion title="Cause: shared secret mismatch" icon="key">
    Webhook source's secret differs from SignalsBot's `TRADINGVIEW_WEBHOOK_SECRET`.

    **Fix**:

    * Verify both sources have the same secret.
    * If you rotated the secret: update every upstream sender.
  </Accordion>

  <Accordion title="Cause: webhook source IP not allowed" icon="ban">
    If you IP-allowlisted at reverse proxy and TradingView's IPs changed (rare but possible).

    **Fix**: refresh allowlist with TradingView's current IPs (their docs publish them).
  </Accordion>

  <Accordion title="Cause: rate-limited" icon="gauge">
    SignalsBot rejects with `429` when exceeding `100 requests / 15 minutes` per IP.

    **Fix**: investigate source — usually a misconfigured strategy flooding signals. Fix the source.
  </Accordion>
</AccordionGroup>

## Bot → external APIs (Telegram, Frankfurter, etc.)

<AccordionGroup>
  <Accordion title="Telegram notifications stopped" icon="paper-plane">
    Already covered in [Common Issues](/troubleshooting/common-issues#issues-with-notifications).

    Quick: check TelegramBot container, verify token, check Telegram API status.
  </Accordion>

  <Accordion title="Tax export fails — Frankfurter unreachable" icon="circle-euro">
    Frankfurter API outage temporarily prevents currency conversion.

    **Fix**: retry later. The service is reliable but occasional outages happen.

    **Fallback**: export without EUR conversion, manually convert later if needed.
  </Accordion>

  <Accordion title="License verification failure" icon="lock">
    Bot occasionally heartbeats to license-verification service. If this fails persistently:

    **Fix**:

    1. Verify VPS has internet access (test with general DNS lookup).
    2. Verify license is current.
    3. Contact support if persistent without obvious cause.
  </Accordion>
</AccordionGroup>

## Diagnostic toolkit

<Steps>
  <Step title="Check VPS connectivity">
    `ping 8.8.8.8` — basic internet works?
  </Step>

  <Step title="Check DNS">
    `nslookup api.binance.com` — DNS resolves?
  </Step>

  <Step title="Check VPS public IP">
    `curl -s https://api.ipify.org` — what's the bot's source IP?
  </Step>

  <Step title="Check NTP">
    `timedatectl status` — is the clock synchronized?
  </Step>

  <Step title="Check container status">
    `docker ps` — all expected containers running?
  </Step>

  <Step title="Check container logs">
    `docker logs <container>` — what is each container saying?
  </Step>

  <Step title="Check port accessibility">
    `netstat -tlnp` — are reverse proxy ports listening?
  </Step>

  <Step title="Check disk and memory">
    `df -h && free -h` — VPS resources OK?
  </Step>

  <Step title="Check the Dashboard's logs panel">
    Centralized view of TradingBot logs.
  </Step>

  <Step title="Check the venue's status page">
    External issue confirmation.
  </Step>
</Steps>

## Best practices

<Tip>
  * ✅ **NTP-sync your VPS clock** — prevents many timestamp-related issues.
  * ✅ **Use a static VPS IP** — avoid IP-allowlist update chores.
  * ✅ **Auto-renewing TLS certificates** — Caddy handles this, set it once.
  * ✅ **External monitoring on critical endpoints** — alerts on downtime.
  * ✅ **Test recovery procedures quarterly** — restoration drills.
  * ✅ **Document VPS provider's status page URL** — operator-runbook entry.
  * ✅ **Regular `docker logs` review** — catches subtle issues before crises.
  * ✅ **Reserve disk capacity** — `20%` free is a comfortable buffer.
  * ✅ **Rotate API keys quarterly** — fresh credentials catch drift.
  * ✅ **Engage kill switch during connectivity investigation** — removes one variable.
</Tip>

## What's next

<CardGroup cols={2}>
  <Card title="Common issues" icon="circle-exclamation" href="/troubleshooting/common-issues">
    Other common problems.
  </Card>

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

  <Card title="Escalation" icon="forward" href="/troubleshooting/escalation">
    When to escalate beyond self-help.
  </Card>

  <Card title="API Key Security" icon="shield" href="/exchanges/api-key-security">
    Includes IP allowlist discipline.
  </Card>

  <Card title="Architecture" icon="server" href="/concepts/architecture">
    The connection topology of unCoded.
  </Card>

  <Card title="Support" icon="life-ring" href="/operations/support">
    For unresolved connectivity issues.
  </Card>
</CardGroup>