NAMEFRAME Frame the world. Name the frames.

Troubleshooting

Symptoms, causes and fixes, ordered roughly by how often they come up.

Unreal connection#

"Connection refused" from capture-unreal, scene-unreal or live-smoke

These commands talk to an already-open editor. NameFrame never launches Unreal.

  1. Is the editor open, with your level loaded?
  2. Is the Remote Control API plugin enabled in the project?
  3. Is anything listening on http://127.0.0.1:30010?
  4. Non-default port or host? Pass --remote-url, or set NAMEFRAME_UE_REMOTE_URL.

The Studio panel is not in the Tools menu

The editor module did not load. Check that the plugin folder is under <YourProject>/Plugins/NameFrameCapture/, that the plugin is enabled, and that Niagara is enabled. Then look at the Output Log for a module load error. A compile failure in the editor module can leave the runtime module loading fine, so the plugin looks "present" while the panel is missing.

The panel says "No editor world"

No level is open. Load one.

Empty or wrong frames#

Frames contain no targets

  1. Are actors assigned to a class? Press Refresh on the Scene page and read the counts. Zero actors means zero labels.
  2. Is the camera pointed at them? Press Preview Camera and look.
  3. Are they inside a spawn zone, and does the zone have an asset pool and a ground?
  4. Turn on viewpoint validation with Min targets = 1, so empty views get resampled instead of written.

Boxes are offset from the objects

This is what pixels-vs-transforms catches. It usually means the scene moved after the transform was recorded. Raise the weather settle time, and check that nothing animates or simulates during capture.

Objects float above or sink into the ground

actor-ground-contact failing. Set the ground actor prefix on the population contract, or select the zone plus your landscape and press Pick Ground. Check that Max ground clearance is not larger than you intend.

Grey, blurry or untextured targets with correct boxes

Frames were captured before shaders and textures finished. Set the performance profile back to safe, or re-enable the wait steps: finish asset compilation, warm target shaders, stream level resources, pin target textures.

Fewer actors than the count you asked for

The placer ran out of attempts. Min spacing is too large for the zone area, the slope limit is rejecting the surface, or the zone is too small. Enlarge the zone, lower the count, or relax the spacing. Validate Setup reports it.

Weather and lighting#

Time of day or weather changes do not affect the lighting

Raise Settle time (seconds), because at zero you capture mid-transition. Also confirm you selected the right driver: UDS/UDW parameters do nothing while the built-in driver is active.

Rain and snow are invisible in the images

Expected. UDS/UDW precipitation is GPU Niagara, which Unreal does not render inside editor scene captures. Enable the precipitation compositing option, either Composite rain and snow particles into generated output in Studio or --precipitation on the CLI.

Daytime frames come out almost black with UDS

A fixed negative exposure bias inherited from a sunny-only render profile. Either remove render.fixed_exposure and render.exposure_bias so the compiler picks adaptive exposure for the dynamic driver, or set them explicitly for the range of times you are capturing.

Quality#

Validation grades C or worse

Open validation/validation.html and read the penalties, because they name the exact problem. The frequent ones:

PenaltyFix
Near-duplicate leakage across splitsSwitch --split-strategy to sequential or by_dump
Blank or near-blank imagesCamera pointing at sky or ground, or exposure wrong
Degenerate boxesTargets clipped at frame edges. Raise the minimum box size in viewpoint validation
Class imbalanceAdjust per-zone counts, or use --filter-require-classes
Empty splitToo few frames for the requested fractions

The same seed produces different output

Run nameframe verify and check the determinism gate, then nameframe hardening-smoke. If both pass offline, the non-determinism is on the Unreal side, usually an animating or physics-simulating actor in the scene.

Command line#

"nameframe: command not found"

The virtualenv is not active, or the package is not installed. Activate it, or use python -m nameframe.cli, which always works.

run says "nothing to do"

run needs at least one stage: --verify, --label-out, --report-out, --dataset-out or --validate-out.

A long run died partway

Re-run the identical command with --resume. Capture gets skipped for frames that already exist, and the offline stages continue from the last completed step.

MCP#

The client connects but every tool fails

Run nameframe mcp-doctor. Most often the API bridge is not running, so start nameframe api-serve first. The other common cause is an API URL that is not loopback, which the config rejects by design.

A write tool returns a dry-run result instead of doing anything

Working as intended. Controlled writes need approved plus an idempotency key, the corresponding write scope granted with --scope, and if an approval store is configured, a human decision in the queue.

Generation is rejected because of the output path

The path is outside the allowlist. Add it with --output-root (absolute paths only), or via NAMEFRAME_MCP_OUTPUT_ROOTS.

CONFIG_CONFLICT on an update

Somebody else changed the scenario since you read it. Re-read current_scenario(), re-apply your patch on the new hash, and retry. That error is the system refusing to let you overwrite newer state.

When nothing above fits#

  1. Reduce to the smallest failing case

    Five frames, one class, fixed camera, clear weather, no lens profile.

  2. Check the demo path still works

    nameframe generate --demo --samples 4 --seed 7 --output _build/check --fail-under 0

    If that fails, the problem is the install rather than your scene.

  3. Read verify.json

    It names the failing gate and why.

  4. Build a support bundle

    nameframe support-bundle _local/support/bundle