Troubleshooting¶

Start with the narrowest boundary that can prove or disprove the problem. Keep the exact project version, instance ID, run ID, resource key, command, and first error message with any incident report.

Installation and builds¶

`aurum` is not found¶

Confirm that the installation prefix’s bin directory is on PATH:

command -v aurum
aurum version

The default user prefix is ~/.local, so a typical executable path is ~/.local/bin/aurum. Open a new shell after changing PATH.

CMake cannot find Aurum¶

Use aurum compile or aurum run from a project created by aurum create. These commands resolve the installed SDK for the project. For a custom build invocation, point CMAKE_PREFIX_PATH at the authorized Aurum installation prefix, not at the source repository.

If the CLI works but the package is still unavailable, verify that a full SDK package was installed. A --cli-only installation intentionally omits C++ headers, libraries, and CMake package files.

Project identity cannot be read¶

aurum push requires literal NAME and VERSION values:

aurum_project(
  NAME signal-watch
  VERSION 0.0.2
)

CMake variables and substitutions are not accepted for these two values. Published versions are immutable, so increment VERSION when Forge reports that name@version already exists.

A topic fails to compile¶

Check the full canonical key, including separators and parameters:

bar://okx/BTCUSDT@1m
book://okx/BTCUSDT@full
order://okx/BTCUSDT/trade

The topic literal determines its payload type at compile time. Use the key returned by a venue factory or the running resource catalog; do not translate a Terminal label into a key. See Resource Contracts.

Local execution¶

The project exits during startup¶

Run it in the foreground and preserve the first error:

aurum run . --log debug

Common causes are an invalid aurum.toml line, an unwritable Aurum home, a port already in use, a missing credential document, or a venue account whose permissions do not satisfy the project declaration. aurum info shows the active home; Configuration documents its supported files.

The project runs but receives no market data¶

Check these in order:

Confirm that the bound venue, symbol, interval, and handler key match.
Keep the foreground process at --log debug and inspect connection errors.
Verify proxy and timeout values in aurum.toml.
Confirm that the venue offers the requested channel in the selected network.
On Forge, inspect runtime status and the resource catalog separately.

An unconfirmed bar has close_timestamp == 0. A handler that intentionally ignores unconfirmed bars can therefore appear idle until the current interval closes.

Credentials are rejected or not found¶

Verify the reference before checking the exchange:

aurum run . --auth okx-live --log debug

okx-live resolves to $AURUM_HOME/secrets/okx-live.toml. The selected [[accounts]] entry must match the venue, credential reference or qualified account name, and requested permissions. For file:// references, use an absolute path. Keep the secret file at mode 0600 and its directory at 0700.

Do not move a local credential into a deployment archive. A remote Forge run resolves the reference in the target environment.

Forge and lifecycle¶

An SSH deployment fails¶

Inspect the registered target, then test the same route outside Aurum:

aurum remote show prod
ssh aurum@forge.example.com aurum version

Resolve host-key, user-key, proxy, port, and remote PATH issues in the normal SSH configuration. aurum push does not bypass SSH policy or prompt reliably in unattended automation.

Forge is reachable but projects are unavailable¶

The API process and its control-plane dependency have separate checks:

curl -fsS https://forge.example.com/api/v1/health
curl -fsS https://forge.example.com/api/v1/doctor

/health confirms the API process. /doctor returns 502 when Forge cannot reach aurumd. If both pass, query /instances and select the exact instanceId rather than a display name.

A lifecycle action succeeds but the project is not ready¶

Start, stop, and restart responses acknowledge a control operation; they do not prove convergence. Poll the instance detail until desired, process, and runtime state agree:

aurum status signal-watch --server prod
aurum logs signal-watch --server prod --journal

Use runtime logs for application behavior and journal logs for managed process startup. A running process with an unreachable runtime endpoint is degraded, not healthy.

Terminal and APIs¶

Terminal cannot connect to Forge¶

Register a browser-reachable HTTP base ending in /api/v1. The SSH address used by aurum push is not a Terminal server URL. Avoid localhost unless both the browser and Terminal server process can reach the intended Forge at their own loopback address.

Test /health and /doctor from the same network path as Terminal. With TLS, also verify that the browser trusts the certificate and can open the derived wss endpoint.

A WebSocket connects but delivers no frames¶

Before subscribing:

fetch /runtime/status?instance=<id> and check available;
verify the required capability is true;
fetch /runtime/resources?instance=<id>;
copy the returned resource key exactly;
subscribe and inspect the per-key acknowledgment.

Subscriptions belong to one connection. After reconnecting or changing project version, fetch the catalog again and resubscribe. For a book sequence gap, request RESYNC and rebuild the projection from the next snapshot.

History is empty or unavailable¶

Live delivery and durable history are independent. Check the resource’s historyModel, then query with an exact run_id. An empty response can be correct when the resource is live-only, the selected run never published it, or ingestion has not produced durable rows.

Use GET /history/instances to confirm that Forge can see historical instances. History uses lowercase readmodel error codes: 404 with latest_run_unavailable means no latest run can be resolved from ingested metadata, while 502 with history_unreachable, history_query_failed, or a resource-specific *_query_failed code means the history dependency or query is failing.

API errors¶

Branch on the HTTP status and structured error.code. Preserve the full response, but treat message and hint as operator text rather than stable program identifiers. Forge control and live routes use uppercase protobuf enum codes; /history/* routes use lowercase readmodel codes and a separate envelope. The common HTTP boundary is:

Status	Interpretation
`400`	Invalid or missing request input.
`404`	Unknown instance, route, or resource.
`409`	The selected run or runtime capability is unavailable.
`502`	Forge cannot reach `aurumd`, the runtime, or history storage.

See REST API for the response envelope and Runtime WebSocket for subscription recovery.