Troubleshooting

Common issues during pipeline runs and how to fix them.

Setup issues

blender: command not found

# macOS
export PATH="/Applications/Blender.app/Contents/MacOS:$PATH"
# or in configs/base.yaml:
# paths:
#   blender_binary: /Applications/Blender.app/Contents/MacOS/Blender

OPENAI_API_KEY / FAL_KEY not set

export OPENAI_API_KEY=sk-...
export FAL_KEY=...
echo $OPENAI_API_KEY | head -c 10   # verify

OpenCode not authenticated

opencode
/connect    # authenticate at opencode.ai/auth

Python import errors

pip install -r requirements.txt
python3 -c "import fal_client, openai, jsonschema, yaml; print('OK')"

Parts analysis

Vague part names (body, part_1)

Symptom: Files named body.glb instead of cabinet_body.glb Fix: Edit parts.json at the human gate. Use specific names: cabinet_body, front_door, lower_rack.

Missing moving parts

Symptom: Drawer or door not in parts list Fix: Add the part with correct joint_type, world_size, world_center, and euler_deg. Re-run from parts gate.

Wrong initial pose

Symptom: Door or drawer pose does not match the source image Fix: Edit world_center and euler_deg in parts.json. Delete iterations/001/assembly.json, then rerun placement init:

python3 tool_scripts/initialize_placement.py --run-dir .intermediate/dishwasher/001

Image generation

Wrong part isolated in PNG

Symptom: PNG shows wrong component or multiple parts Fix: Improve part description in parts.json. Delete affected PNGs in component_images/ (and corresponding GLBs if needed), resume run.

OpenAI rate limit (429)

Fix: Wait and re-run. generate_components.py skips existing PNGs and GLBs.

Images don't match source style

Fix: Verify <run_dir>/source.png exists, generate_components.py uses it as the reference image for every part.

3D mesh generation

fal.ai timeout or credits exhausted

Symptom: Script fails partway; some GLBs missing Fix: Top up fal.ai credits. Re-run, skips existing GLBs.

export FAL_KEY=...
opencode run --agent orchestrator -- "resume .intermediate/dishwasher/001/"

Bad mesh quality (lumpy, incomplete)

Fix:

1. Regenerate source PNG with better description
2. Increase face_count in configs/base.yaml (e.g. 80000)
3. Re-run fal step only

GLB size seems wrong

Symptom: Part appears much larger/smaller than expected Note: Raw GLB sizes vary, this is normal. initialize_placement.py derives node_scale from world_size and raw dims; the critic loop corrects scale via corrected_world_size in critic.json.

Placement loop

Parts at wrong scale

Symptom: Door 2× too wide, rack too small Fix:

1. Check node_scale and world_size in iterations/001/assembly.json
2. Verify world_size, world_center, and euler_deg in parts.json
3. Delete iterations/001/assembly.json and rerun initialize_placement.py

Mesh collisions (overlap)

Symptom: Parts interpenetrate in renders Fix: Critic should flag this. If not, run more iterations or adjust world_center in assembly.json.

Door at wrong angle

Symptom: Door closed when source shows open Fix:

1. Check world_center and euler_deg in parts.json
2. Delete iterations/001/assembly.json, rerun initialize_placement.py
3. Let critic correct via suggested_rotation_delta

Score plateaus below threshold

Symptom: Score stuck at 70-75 after many iterations Fix:

1. Check if critic locks components too early
2. Edit parts.json placement numbers, regenerate placement init
3. Increase max_loops in configs/base.yaml
4. Lower score_threshold if 75-80 is acceptable for your use case

Score regresses

Symptom: Iteration 5 worse than iteration 3 Note: Orchestrator tracks best iteration automatically. Next placement bases on best-scoring layout.

Rendering

Black or dark renders

Fix: Increase light_energy in render_views.json (default 5.0 → try 8.0).

Slow rendering (>2 min per iteration)

Fix in configs/base.yaml:

render:
  resolution: [1280, 720]
  samples: 32

USD export

Orchestrator won't start USD export

Symptom: Stops after placement loop Fix: Complete placement human gate, or manually write:

# Tell the orchestrator to export iteration 006 after reviewing renders

Missing textures in Isaac Sim

Fix: Ensure textures/ exists next to robot.usda. Re-export if needed.

Asset tipped on its side in Isaac Sim

Note: Exporter uses convert_orientation=False for Z-up. Check Isaac Sim stage up-axis settings.

moov atom not found / invalid MP4

Symptom: Video file won't play; file reports "JSON data" Fix: The file is an API error response saved with .mp4 extension. Re-generate the video; validate binary before saving.

Validation failures

Schema validation errors after subagent write

The orchestrator auto-retries up to max_validation_retries. If persistent:

Validate manually:

python3 tool_scripts/common.py \
  --schema schemas/assembly.schema.json \
  --data .intermediate/dishwasher/001/iterations/006/assembly.json

Resume and recovery

Check run state

RUN=.intermediate/dishwasher/001
ls $RUN/parts.json $RUN/component_glbs/ $RUN/iterations/
ls $RUN/robot.usda 2>/dev/null || echo "USD not yet exported"

Force redo from a specific step

# Redo placement from iteration 3
rm -rf .intermediate/dishwasher/001/iterations/003/
opencode run --agent orchestrator -- "redo placement from iteration 3 for .intermediate/dishwasher/001/"
 
# Redo image gen and everything after
rm -rf .intermediate/dishwasher/001/component_images/ .intermediate/dishwasher/001/component_glbs/
opencode run --agent orchestrator -- "resume .intermediate/dishwasher/001/"

Bring your own GLBs

mkdir -p .intermediate/my_object/001/component_glbs
cp my_meshes/*.glb .intermediate/my_object/001/component_glbs/
# Also need parts.json, write or run analyze first
opencode run --agent orchestrator -- "resume .intermediate/my_object/001/"

Getting help

1. List run directory: ls -la .intermediate/<asset>/<NNN>/
2. Validate artifacts: see Schema validation
3. Open assembled.blend in Blender for visual debugging
4. Check orchestrator's last message for step-specific errors