Skip to main content
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 if you are unsure where the problem lies.
The backend runs as a local process on port 8080. Use fintheon status to see its state at a glance:
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:
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.
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.
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:
fintheon restart stops any stale processes and starts fresh. If the log shows the same error after a restart, check the port conflict and full reset sections below for further steps.
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:
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.
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.
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:
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.
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:
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.
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.
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:
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 steps.Step 3 — Restart. If the feed is still stalled after Steps 1 and 2:
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:
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.
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.
This deletes your local Fintheon codebase and all locally built files. It does not delete your account, settings, or trade history.
Then re-run the installer using Option A (one-liner) or Option B (clone first) from the CLI install guide:
After install completes, sign in with Google. Your preferences, RiskFlow calibration, and billing information are restored from the cloud automatically.

​
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:
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.