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

# Troubleshooting

> The sharp edges of the headless host — what returns ok-but-does-nothing, what needs a resource or a GPU, and the lossy paths — with the fix for each.

Most surprises come from running on a **bare headless host** (`euca-studio --headless`): it runs the
project's full game logic, but has no GPU and registers only the engine-level resources — anything a
subsystem needs beyond that (a script VM, a template registry, an input action map, an audio device, a
GPU) must come from the project's game or the host. Here are the common ones, each verified against a
running server.

## "I set the camera / a material, but nothing renders"

The camera **pose** is plain CPU state, so the headless host serves it: `GET /camera` returns the pose and
`POST /camera` / view / focus mutate it. What's missing is the **GPU edge** — there is no renderer, so
`POST /material/set` returns `ok` but draws nothing, and `/screenshot` returns `503` (no `ScreenshotChannel`).
**Fix:** run on a GPU/render host — see [Camera & rendering](/systems/camera-and-rendering). `GET /engine/gpu`
returns an error in headless mode by design.

## "/template/create returns ok but /template/spawn says 'not found'"

The default server registers no `TemplateRegistry`, and the create handler only stores `if let
Some(registry)`. So create no-ops (still returns `ok`) and the template never exists. **Fix:** register a
`TemplateRegistry`/`PrefabRegistry` on your server build — see
[Templates & prefabs](/systems/templates-and-prefabs).

## "/input/bind does nothing and /input/list is empty"

No `ActionMap` is registered by default, so bind silently no-ops. The context stack
(`/input/context/*`) does work. **Fix:** register an `ActionMap` — see [Input](/systems/input).

## "/script/load returns 'No ScriptEngine resource in world'"

Lua isn't enabled on the default server — no `ScriptEngine` resource. **Fix:** register a `ScriptEngine`
— see [Scripting (Lua)](/systems/scripting-lua).

## "Audio calls succeed but I hear nothing"

Audio needs an OS audio device (Kira); the headless host doesn't run one. The route logic is
headless, but playback is client-side — see [Audio](/systems/audio).

## "Entity positions read \[0,0,0] right after spawning"

`GlobalTransform` propagates on `/step`. **Fix:** `POST /step` once after spawning before reading
positions. A `velocity` also only integrates if the entity has a `physics_body`.

## "Save → load didn't restore my world exactly"

`/scene/save` + `/scene/load` (and the scenario world→spawn extraction) restore only **position, scale,
health, team** — they drop velocity, rotation, and gameplay state. **Fix:** for exact reproducibility use
[snapshots](/guides/snapshots) and the [`state_digest`](/concepts/determinism); use scene/level files for
authoring/layout. See [Scenes & levels](/systems/scenes-and-levels).

## "An injected event seems to apply on two consecutive steps"

Events are double-buffered; an event injected over HTTP can be read on the tick it's sent and the next
before the buffer swaps. Within a single tick each event is applied once. Step deterministically and read
state with [`observe`](/concepts/query-verbs) rather than counting event reads.

## "POST returns 'missing Content-Type' or a parse error"

All POSTs require `Content-Type: application/json`. Empty-body POSTs should send `{}`.

<Card title="Configuration" icon="gear" href="/reference/configuration" horizontal>
  Ports, limits, and what the headless host registers.
</Card>