Skip to content

Troubleshooting ​

Start with the failed boundary: installation, environment construction, a request, gameplay state, or capture.

SymptomNext check
Cargo cannot find bevy_agentDepend on the named runtime crates; there is no umbrella package
Installed CLI is unrelatedInstall bevy_agent_cli; its executable is agentctl
Compilation requires a newer RustUse Rust 1.91+ and the Bevy 0.18.1 manifest in Getting started
AgentApp::new returns an errorInstall both extractors, declare metadata/catalogs, and register required state before construction
An action is rejectedQuery action-space and schema; match the game's supported action and custom JSON Schema
Observation fails validationSchema the full envelope, including kind, tick, and value
Gameplay changes without a controlled stepMove authoritative systems into AgentTick; remove frame-time or presentation input from the simulation
Snapshot restore changes later behaviorRegister hidden state, RNG, required resources, stable type identities, and gameplay entity IDs
Client cannot connectStart a server; check its listener and the /rpc endpoint; the CLI alone starts no game
HTTP 200 contains an errorRead JSON-RPC error; verify the session token and required capability
Replay export or capture cannot write a fileEnable FILESYSTEM and configure an artifact root on the server
A PNG appears in an unexpected directoryPaths resolve on the server under the artifact root, not the client working directory
A timed-out step might have executedLook up its operation or retry key before issuing another mutation
recovery_required is trueSuccessfully reset before further gameplay access
An old replay will not loadCurrent artifacts use format 3; regenerate incompatible files
A past tick is unavailableCheck retained checkpoints/history and memory budgets
Primary-window capture is unavailableEnable visual, run a rendered app, and use the Bevy main-thread integration

The complete counter is the smallest known-good integration. Compare its registrations with your app before debugging a full game.

For protocol details, use JSON-RPC methods. For design constraints, use Architecture.

Released under MIT or Apache-2.0.