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

# Troubleshooting Fintheon Issues

> Solutions for common Fintheon problems: backend startup failures, port conflicts, macOS Gatekeeper blocks, Harper errors, RiskFlow gaps, and more.

If something in Fintheon is not behaving as expected, the sections below cover the most common issues and how to resolve them. Start with [checking whether the backend is running](#how-to-check-if-the-backend-is-running) if you are unsure where the problem lies.

<AccordionGroup>
  <Accordion title="How to check if the backend is running">
    The backend runs as a local process on port 8080. Use `fintheon status` to see its state at a glance:

    ```bash theme={null}
    fintheon status
    ```

    The output shows whether the backend is listening on `:8080`, whether the app is running, and the current version. If the backend is up, you also see a JSON health snapshot from the `/health` endpoint.

    If the status shows the backend is not running, tail the log to see why it stopped or failed to start:

    ```bash theme={null}
    fintheon logs
    ```

    The log file at `/tmp/fintheon-backend.log` captures all backend output since the last start. Look for lines with `error` or `failed` near the bottom of the file.
  </Accordion>

  <Accordion title="Backend won't start">
    If `fintheon start` completes without error but the backend is not running, or if the backend crashes immediately, the log file is the first place to look.

    ```bash theme={null}
    tail -f /tmp/fintheon-backend.log
    ```

    Scan for error messages at the bottom of the file. Common causes include a missing dependency, a port conflict, or a failed service connection. After identifying the cause:

    ```bash theme={null}
    fintheon restart
    ```

    `fintheon restart` stops any stale processes and starts fresh. If the log shows the same error after a restart, check the [port conflict](#port-8080-is-stuck-or-already-in-use) and [full reset](#full-reset) sections below for further steps.
  </Accordion>

  <Accordion title="Port 8080 is stuck or already in use">
    The backend requires port 8080. If another process is holding that port — from a previous crash or a different application — the backend will fail to bind and exit immediately.

    Kill whatever is on port 8080, then start Fintheon again:

    ```bash theme={null}
    lsof -ti:8080 | xargs kill -9
    fintheon start
    ```

    `lsof -ti:8080` lists the process IDs listening on port 8080. Piping to `xargs kill -9` terminates them forcefully. Then `fintheon start` claims the port for the backend.

    <Note>
      `fintheon start` already attempts to clear port 8080 before launching. Run the manual `lsof` command above only if `fintheon start` still reports a port conflict after the first attempt.
    </Note>
  </Accordion>

  <Accordion title="macOS Gatekeeper blocks the app from opening">
    macOS Gatekeeper may prevent Fintheon from opening if the app bundle's quarantine flag was set when it was downloaded. You will see a message such as "Fintheon can't be opened because Apple cannot check it for malicious software."

    Remove the quarantine attribute from the app bundle:

    ```bash theme={null}
    xattr -cr /Applications/Fintheon.app
    ```

    After running this command, open Fintheon from `/Applications` normally. You should not need to repeat this step unless the app is re-downloaded or updated via a new `.dmg`.
  </Accordion>

  <Accordion title="Harper is not responding or VProxy is unavailable">
    Harper uses VProxy, a local OAuth gateway, to route inference requests to Anthropic. If VProxy is not running or its authorization has expired, Harper will fail to respond or will return errors in the chat panel.

    **Quick workaround:** Open the AI provider dropdown in the CAO chat panel and switch to **Nous** or **ORouter**. These providers do not depend on VProxy and will restore Harper's responses immediately.

    **To fix VProxy:** Reconnect your Anthropic subscription by running the OAuth flow from the terminal:

    ```bash theme={null}
    fintheon oauth
    ```

    A browser window opens. Click **Allow** to re-authorize. Once complete, switch the chat provider back to the VProxy/Local option if you prefer using your Anthropic subscription directly.

    <Tip>
      If `fintheon oauth` runs but Harper is still unresponsive, check the backend log (`fintheon logs`) for errors containing `vproxy` or `8317`. Restarting the backend after re-authorization often resolves the issue: `fintheon restart`.
    </Tip>
  </Accordion>

  <Accordion title="RiskFlow is not updating">
    If the RiskFlow feed in the Strategium panel appears frozen or stops showing new items, the most likely causes are a scoring pipeline stall or a polling issue with the X feed.

    **Step 1 — Run the Doctor button.** Open the Strategium panel, locate the RiskFlow section, and click the **Doctor** button. This triggers a health check that attempts to restart the scoring pipeline and flush any stalled queue.

    **Step 2 — Check the backend log.** If the Doctor button does not restore the feed within a minute, look for errors in the log:

    ```bash theme={null}
    fintheon logs
    ```

    Errors mentioning `riskflow`, `rettiwt`, or `polling` indicate a feed authentication problem. Go to Settings › API and verify that your X feed keys are present and active. If the pool shows zero available keys, add a new key following the [X Feed Authentication](/configuration/settings#x-feed-authentication) steps.

    **Step 3 — Restart.** If the feed is still stalled after Steps 1 and 2:

    ```bash theme={null}
    fintheon restart
    ```
  </Accordion>

  <Accordion title="Update fails or gets stuck">
    `fintheon update` pulls the latest code and rebuilds. If it stalls or exits with an error, a running backend process sometimes locks files that the build needs.

    Stop Fintheon first, then run the update:

    ```bash theme={null}
    fintheon stop
    fintheon update
    ```

    If the update still fails after stopping, check `/tmp/fintheon-backend.log` for build errors from the previous session and clear any partial build artifacts by running `fintheon stop` once more before retrying.
  </Accordion>

  <Accordion title="Full reset">
    If Fintheon is in a broken state that none of the above steps resolve, a full reset removes the local installation and starts fresh from the installer. Your account, settings, and cloud data are not affected — they are stored server-side and restored after you sign in again.

    <Warning>
      This deletes your local Fintheon codebase and all locally built files. It does not delete your account, settings, or trade history.
    </Warning>

    ```bash theme={null}
    rm -rf ~/Documents/Codebases/fintheon
    ```

    Then re-run the installer using Option A (one-liner) or Option B (clone first) from the [CLI install guide](/configuration/cli#fintheon-install):

    ```bash theme={null}
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/solvys-technologies/fintheon/main/scripts/fintheon-setup.sh)"
    ```

    After install completes, sign in with Google. Your preferences, RiskFlow calibration, and billing information are restored from the cloud automatically.
  </Accordion>
</AccordionGroup>

***

## Diagnostics endpoint

Fintheon's backend exposes a health check endpoint at `GET /api/diagnostics` that returns the status of all platform services. The app uses this endpoint internally to monitor health, but you can query it directly when investigating a specific service failure:

```bash theme={null}
curl http://localhost:8080/api/diagnostics | python3 -m json.tool
```

Look for any service showing a non-`ok` status in the response. If a specific service is failing, `fintheon restart` will attempt to reinitialize it. For persistent failures, check `fintheon logs` for the corresponding error messages.