Debug Render Failure

Use this skill when debugging render pipeline issues.

Environment

• APPRENDERDRY_RUN=1 – Run full pipeline without paid APIs; outputs are placeholder files.
• APPDRYRUNFAILSTEP=<step> – Simulate failure at a specific step. Valid steps: ttsgenerate, asralign, imagesgenerate, captionsbuild, musicbuild, ffmpegrender, finalize_artifacts.
• APPDRYRUNSTEPDELAY_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 APPRENDERDRYRUN=1 and optionally APPDRYRUNFAIL_STEP to test error handling.
4. Ensure FFmpeg is available when not in dry-run; check ARTIFACTS_DIR and disk space.

References

• [renderPipeline.ts](apps/server/src/services/render/renderPipeline.ts), [run routes](apps/server/src/routes/run.ts)
• [.github/copilot-instructions.md](.github/copilot-instructions.md) (Test Modes, Debug render failures)