Debug Render Failure

Use this skill when debugging render pipeline issues.

Environment

• APP_RENDER_DRY_RUN=1 – Run full pipeline without paid APIs; outputs are placeholder files.
• APP_DRY_RUN_FAIL_STEP= – Simulate failure at a specific step. Valid steps: tts_generate, asr_align, images_generate, captions_build, music_build, ffmpeg_render, finalize_artifacts.
• APP_DRY_RUN_STEP_DELAY_MS – Optional delay (ms) before each dry-run step.

Where to look

• Run state: Run.logsJson (array of log messages), Run.resumeStateJson (completed steps, resume data). DB via Prisma or db:studio.
• Pipeline: apps/server/src/services/render/renderPipeline.ts. Check completedSteps, saveResumeState, handlePipelineError, and queue processing (processNextInQueue).
• Retry: POST /api/run/:runId/retry supports optional fromStep to resume from a specific step.

Checks

1. Confirm Run status (queued / running / failed / done / canceled / qa_failed).
2. Inspect logsJson and resumeStateJson for the last completed step and error message.
3. Reproduce with APP_RENDER_DRY_RUN=1 and optionally APP_DRY_RUN_FAIL_STEP to test error handling.
4. Ensure FFmpeg is available when not in dry-run; check ARTIFACTS_DIR and disk space.

References

• renderPipeline.ts, run routes
• .github/copilot-instructions.md (Test Modes, Debug render failures)