Troubleshooting

Cause

Almost every 3.0 problem is visible to the management CLI, which knows the state of the installation, the databases and each component.

Fix

Run the manager first and keep its exit status: "$HOME/predict-profit/bin/predict-profit" doctor --json "$HOME/predict-profit/bin/predict-profit" status A provider check reported as NOT CHECKED is not a passing provider test. Private phase evidence is in shared/logs/setup.log.

Cause

Setup records its progress and your choices, so an interrupted run resumes rather than starting over.

Fix

Rerun configure on the same permanent root and confirm the resume: "$HOME/predict-profit/bin/predict-profit" configure Completed work is checked and reused. Do not delete journals or receipts to force setup past a failed phase, and do not put a guessed account ID into a template.

Cause

It detected an existing bot installation. The Installation question comes before any legacy credential read or database inspection, and it defaults to migrate.

Fix

Choosing migrate validates legacy credentials without changing the source, then exits and prints the exact migrate inspect command to run next. Choosing fresh discards every detected legacy source and creates a separate installation. To change that decision before provisioning starts: "$HOME/predict-profit/bin/predict-profit" configure --restart-setup

Cause

Environment files and PEM private keys must be mode 0600 and managed credential directories 0700. Mode 0670 permits group writes and is rejected, as are symlinks, hardlinks and wrong ownership.

Fix

The error states the current owner and mode, the expected owner and mode, and the remediation. Setup never modifies your source files. For a migration, approve the private staging copy or supply an explicit private credential file, then resume.

Cause

3.0 stores trading, risk and dashboard state in PostgreSQL 16 or 17. Setup detects a local socket and tries current-user peer administration, and also needs a loopback TCP listener for the generated password-authenticated runtime roles.

Fix

No database administrator password or authentication rewrite is needed for the supported paths. To select an explicit socket or a remote server before provisioning: "$HOME/predict-profit/bin/predict-profit" configure --advanced A remote server requires a valid hostname and CA certificate for verify-full TLS. Do not substitute an unrelated database or an administrator login to suppress an ownership failure.

Cause

Setup authenticates the communications principal with a signed GET request. An empty order history is valid, but a failed principal or conflicting order-user identities fail closed.

Fix

Confirm the API key ID and the downloaded private-key path are both for the same Kalshi account and environment. A genuinely changed principal requires explicit account migration and reconciliation rather than a new key in the old installation.

Cause

The dashboard binds receipt-bound listener ports chosen during setup.

Fix

Identify the listener owner and leave unrelated services alone. Choose unused ports through Advanced before provisioning. After provisioning begins, ports, namespace and connection changes require a reviewed migration, so resume the bound configuration instead of editing receipts.

Cause

A running process is not the same as a healthy application, and the API must be healthy before the gateway can proxy it.

Fix

Read the manager status and the matching files under shared/logs/. Verify your configured gateway address and any tunnel or reverse proxy in front of it. Do not treat an existing PID file or a successful spawn as a healthy component.

Cause

Releases are immutable. The manager rejects mismatched versions, unsafe archive paths and links that escape managed storage.

Fix

Keep the ZIP and its .sha256 together and verify the checksum from the same trusted release source before installing. Do not modify an extracted release or reuse a changed archive under the same version. Preserve the rejected artifact and the error for support.

Cause

The management journal records each transition so the same operation can be retried safely.

Fix

Run status and doctor, then rerun the same operation with the same artifact. Do not delete the journal, repoint current by hand, or overwrite an active release to make a command continue. If recovery reports it cannot establish a safe active release, keep the installation stopped and preserve the journal and logs.

Cause

Application rollback selects older code, but it must preserve newer trading records. An irreversible data change cannot be rolled back.

Fix

Read UPGRADE.md in the package. Do not restore an old database snapshot just to select earlier code; that discards financial history the newer release has already recorded.

Cause

Installation does not start trading. Activation is a separate explicit step, and unresolved submissions, halt state, incomplete imports or account-ownership conflicts hold it closed.

Fix

Read the trading diagnostics guide in docs/customer/. These checks need evidence-based reconciliation. Do not clear them as if they were an installation defect; that is the safety behaviour working.

Cause

Yes. Most markets are expected to produce no trade. The weather bot also skips same-day markets entirely, because NBM coverage begins at forecast hour 24. Those show a skip reason of no_forecast_available, which is a coverage gap rather than a threshold rejection.

Fix

Loosening filters will not surface a market with no forecast coverage. Wait for an NBM update; NBM runs hourly and the bot walks back through recent cycles until one fetches. Check the dashboard's decision view for the actual rejection reasons before changing any threshold.

Cause

The inflation bot found that its current model view contradicts an existing open position, or that a new trade would create a logically contradictory pair of positions.

Fix

A conflict rejection is the safety net working, and no action is required. A regime warning is informational: the bot keeps running, and you decide whether to close the flagged position yourself. Review both in the dashboard rather than in raw logs.

Cause

No. Installation completes in dry mode, which reads market data and records what it would have done without placing an order.

Fix

Run dry for at least one to two weeks and confirm authentication, market discovery, decision logging, settlement handling and your risk limits before you activate live trading.

Cause

Native Windows lifecycle operation is not supported in 3.0. The Linux procedure is authoritative.

Fix

Run the application on Ubuntu 24.04. On a Windows machine that means WSL2. Windows is fine as your browser or SSH client, or as a separately configured PostgreSQL server.

Cause

A redacted diagnostic resolves most issues in one reply; a screenshot of a stack trace usually does not.

Fix

Send the release version and checksum, your operating system, Python and PostgreSQL versions, the redacted doctor result, component status and the exact error. Review logs before sharing them. Never attach credential environment files, setup choices, installation receipts, database dumps, private keys, session secrets or unredacted connection strings.