| Symptom |
Cause |
Fix |
Cannot find module '.../skia.node' |
skia-canvas install script was blocked |
approve it (Getting started), then npm rebuild skia-canvas |
| Import fails immediately |
Node < 22, or not an ES module project |
upgrade Node; set "type": "module" |
| No adapter / GPU error |
no WebGPU-capable GPU (VM, plain CI runner) |
render on a machine with Metal or Vulkan; there is no CPU fallback |
| Symptom |
Cause |
Fix |
| Whole frame black |
font not registered, or NaN from a signal |
register every family before building text; keep signal outputs finite |
| Text missing or tofu |
family name doesn’t match a registered font |
match fontFamily to the family you registered |
| Emoji missing |
no emoji font |
FontManager.registerEmojiFont(...) |
| Layer invisible |
path wrong, opacity 0, off canvas, or LFS pointer |
check comp.lint(); run git lfs pull |
| Text clipped |
box narrower than the text |
set width (or width: "fill") |
| Animation stops early |
keys past durationFrames |
extend the layer (animation_truncated) |
| Layer jumps to the corner when animated |
animated y from 0 instead of its layout value |
animate to the placed value |
| Fades look murky grey |
custom shader with straight alpha |
output premultiplied alpha, blend with srcFactor: "one" |
| Metal/rough looks flat |
no environment |
add Layer.environment() or Lighting.studio() |
| Effect does nothing |
strength on a 0–1 scale where it’s 0–100 |
check ranges in the Effects reference |
| Symptom |
Cause |
Fix |
| Audio cuts out early |
Layer.audio without durationFrames |
set durationFrames: totalFrames |
audio_clipping |
mix too hot |
lower volumes; softLimit SFX beds |
loudness_off_target |
mix level |
adjust volume toward the targetLufs |
| Symptom |
Cause |
Fix |
| Script never exits after rendering |
native GPU/encoder threads |
process.exit() at the end |
| Slow exports |
too little parallelism or a shallow staging ring |
raise concurrency; try ringCapacity: 4 |
| Symptom |
Cause |
Fix |
| Cutout empty on a single still |
vision reads the previous frame |
render two consecutive frames with one renderer, keep the last |
| Ghosted double of the subject |
frames rendered out of order (grid, jumps) |
verify with the MP4 or consecutive frames |
| Wrong object cut out |
subject choice |
classes: ["person"] |
| Garment drops out |
fast motion |
variant: "m" or keyBackground: true |
| Halo on dark backgrounds |
feathering |
lower featherRadius or raise maskThreshold |
| Fails offline / in CI |
models not cached |
preload into $FRAMEFIELDS_MODELS_DIR or set FRAMEFIELDS_MODELS_BASE_URL |
| Symptom |
Cause |
Fix |
| Font or media 404 in the page |
path built from process.cwd() |
build paths from import.meta.url; pass root for folders outside the project |
| “No WebGPU” |
browser without WebGPU |
current Chrome, Edge or Safari |
| Preview stopped |
last tab closed (5 s), or replaced |
run it again; same URL |
| Cutouts look wrong while playing |
device skipped frames |
check paused, or in the export |
Still stuck? Open an issue at github.com/gatewai-dev/framefields or ask on Discord.
