Troubleshooting

The app will not start

"No WebGPU adapter"

Your browser has no WebGPU, or has it disabled.

Chrome or Edge on Linux: stock Chrome finds no adapter. Use the launch switches in browser and hardware. The chrome://flags pair alone gets you only the software adapter.
Firefox before 141 (Windows) or 145 (macOS ARM): set dom.webgpu.enabled and dom.webgpu.workers.enabled in about:config.
Safari: needs 26 or later.
Any of the above: the desktop application bundles a Chromium with WebGPU configured and sidesteps this entirely.

"Software adapter" warning

You have landed on SwiftShader. It works, but it is slow and caps buffers at one gigabyte, so 45-megapixel frames will be refused.

On Linux this almost always means VulkanFromANGLE,DefaultANGLEVulkan is missing from the launch switches, or Chrome was already running with the same profile and ignored them — use --user-data-dir for a separate profile.

A black window on Linux

Chromium's Wayland backend does not present with Vulkan enabled; the window maps and stays blank. Add --ozone-platform=x11 to run on XWayland.

If you used --use-angle=vulkan (the flags page's "ANGLE graphics backend = Vulkan"), remove it: on NVIDIA under Wayland it makes the accelerated 2D canvas paint black, so the app shows nothing. Leave that flag at Default and use the --enable-features trio instead.

Frames are refused

"Frames do not fit"

A 45-megapixel frame needs a 550 MB storage buffer, within the adapter's maxBufferSize and maxStorageBufferBindingSize, and about 3.5 GB of GPU memory in total. The app checks before the run rather than failing halfway.

Turn on draft in the parameter panel to work at a fraction of the size, or use the command-line tool, which has no GPU requirement at all.

"Frames of two sizes"

A frame that is not frame 0's size is resampled to it and the run says so — that is not an error. In a batch, a stack whose frames genuinely cannot be reconciled is reported and the batch goes on.

A raw will not open

Raws are recognized by extension. If the extension is unusual, rename a copy to the standard one for that camera. A build without the raw feature refuses raw files outright.

The result is wrong

Soft bands across the subject

The focus step was too large: there is a band of depth no frame saw sharp. No setting fixes this. Reshoot with a smaller step.

To confirm it, turn on peaking on the Source view and scrub. If consecutive frames' magenta bands do not overlap, that is your answer. See the depth map.

Ghosting, doubled edges

Something moved between frames — wind, a live subject, a settling fiber — or the alignment model was not enough for the capture.

Try --align-model affine, or projective if the camera tilted as it stepped.
Lower --align-coarsen if you can see sub-pixel misregistration.
Exclude the offending frames in the filmstrip, or with --skip.

A soft rim around a bright object

The pyramid's halo. Raise halo control from 0 and run again — 1 to 4 is the useful range. See fusion.

Fringing where hair or bristles cross a background

The hard case. A pixel there genuinely contains two things at two depths.

Run LAP + DFR and retouch between them, or try DFR from slabs, which gets LAP's detail within a slab without the whole stack's frames blending in. See other renderings.

Patchy brightness, visible seams between winners

Frames differ in exposure and the region-energy rule is seeing it. Make sure equalize brightness is on (it is by default; --no-brightness turns it off). If it is on and the patches persist, the frames differ by more than a gain can fix — check that nothing was shot with automatic exposure.

Dust spots, sharper than in any frame

The region-energy rule reads a spot's edge as detail. Shoot a dust map and load it.

The 3D relief looks inside out

The near end was guessed wrong. Set near end explicitly in the Save step, or --near-end first | last on the command line. The run's log says which cue decided.

Do not trust the scale trend to tell you: on a rail the near frames are the larger ones, but an internal-focus lens that widens as it focuses closer breathes the other way.

The 3D model is too flat, or absurdly deep

--mesh-relief is a guess — the depth map measures distance in frame indices, and converting that to a proportion of the image width needs your step size. Measure the subject, or set it by eye. Default is 25 % of the image width.

Large dark areas in the confidence map

Those are places the depth was inferred from neighbors, not measured: flat, noisy or ambiguous regions. The depth map there is a plausible interpolation.

It is not necessarily a problem for the stacked image — the fusion does not use the depth map — but it matters if you are about to build a 3D model, make a stereo pair, or measure something.

The run is slow

Symptom	Cause	Fix
Every frame takes seconds	Alignment at full resolution	`--align-coarsen 2` — the CLI default is 0
Every frame takes seconds, raws	Raw development	Develop to TIFF once, identically, and stack those
`--no-align` is no faster	Decode-bound on PNG	Use uncompressed TIFF
Native run feels twice as slow as it should	The pooling allocator is off	Unset `LAPSTACK_NO_POOL`
You have an NVIDIA GPU and are not using it	—	Build with `--features gpu`, run with `--gpu --gpu-align`

And in all cases: --draft 2 while you are still deciding.

Files and saving

A batch saved nothing

Set up the Save step first. A batch saves the files ticked there, with that step's names and settings. Nothing ticked, nothing saved.

The browser asked permission several times

Saving several files at once as downloads triggers that. Choose a folder with save to folder… instead (Chrome and Edge).

"This browser cannot open a folder for writing"

Only Chrome and Edge have the File System Access API. Elsewhere files come out as downloads.

The GIF is enormous

A full-resolution GIF of a long 45-megapixel stack runs to gigabytes. Set a long edge, a frame step, or both. Or choose MP4 or WebM in the section's format.

The video export refuses a size

No encoder the browser has will take that frame size. Reduce the long edge.

"DNG, linear (camera space)" is grayed out

The run was made without the linear DNG option ticked in the Run ▾ menu. It has to be decided before the run, because it changes how the frames are developed. Run again with it on.

A verifier says the content credential's signer is unknown

That is expected and correct. The certificate is self-signed and generated in your browser; it is on no trust list. The credential proves the file has not been altered since lapstack wrote it and records how it was made — it does not attest to who you are. See saving.