Troubleshooting

Reduce failures to a small representative crop while keeping the failing boundary, dtype and image-selection conditions. Then compare two different block grids. This separates a numerical problem from a dependency or ownership problem more effectively than repeatedly increasing memory or adding a halo.

Plan-time refusals

Refusal Why it matters Appropriate response
Unsupported dtype BlockOp::accepts defaults to f64; concrete operations can widen their contract Select a supported kernel or add an explicit planned conversion
Undeclared supplied-image dtype An external image has no producer from which the plan can infer its type State it in SourceInput::holding or the source leaf
Invalid source region or lattice A consumer’s coordinate contract cannot be satisfied by the attached source Correct selection, geometry or explicit resampling
Block constraint cannot be met A whole axis, tile alignment or operation-specific grid rule is required Use a compatible grid or another algorithm
Reduction without barrier The reduction has no defined moment when its input set is complete Use the proper barrier phase contract

A loud refusal is useful evidence. Bypassing it by loading a source directly inside an operation removes the planner’s ability to order, price and retain that source; it does not repair the contract.

Visible seams or changing answers

If grid lines appear in an intensity output, compare values on both sides of an internal seam. A true image boundary can use clamping, padding or another stated boundary policy. An internal block edge must use the real neighboring image values. Applying a boundary extension separately to every tile often produces a plausible complete image with the wrong answer.

For a composed chain, trace requirements backward. Two local filters can need the sum of their reaches, not the maximum. For a mapped operation, inspect its actual source footprint rather than assuming a constant symmetric radius. The halo guide maps these cases to the declarations used by real operations.

For labels or detections, look for ownership errors. An object overlapping two read windows must not be emitted twice merely because both workers saw it. The core that owns its anchor should emit the result once; component algorithms need the explicit seam merge that makes IDs consistent. Comparing counts alone can miss a duplicated object that is balanced by a lost one.

Memory and concurrency

A pipeline can be planned and still contain a resident whole-volume solve. Check the operation catalog for whole-axis and global requirements. Bounded surrounding reads do not change the memory complexity of that solve.

If fewer workers run than requested, inspect the number of ready tasks and the active-memory charge. Too few blocks, a barrier, a wide source footprint or a memory-limited phase can all explain it. First reduce retained images and concurrency when appropriate; if one task itself cannot fit, change block geometry or the algorithm. Do not reduce required reach to make its memory estimate smaller.

The process cap relies on declared buffers and cooperative leases. Include source caches, codecs, model workspaces and application-owned arrays when investigating RSS. Loading the entire input to generate a fixture is acceptable for that small preparation command; doing so in the processing path defeats the large-image design.

Output and physical coordinates

An intermediate that disappeared may have reached its last reader. Retain the necessary image through Hints::keep_images; its work path is not a promise of persistent output. If publication fails, distinguish a valid computed work array from a fully installed image group.

Label pyramids require uint64 identities and nearest-label reduction. An existing destination is often refused intentionally. Use a fresh output or the example’s documented replacement mechanism; do not delete source acquisition data to satisfy a scratch-directory expectation.

For shifted geometry, check channel/time/level, z/y/x ordering, physical origin, spacing, units and the direction of the coordinate map. A centered resize can change translation as well as scale. Equal shapes and similarly named files do not prove physical registration.

Choose the right numerical check

Compare a small kernel with an independent formula or reference first, then run the actual planned route across grids and worker counts. Use bitwise equality when the arithmetic order is preserved and justified tolerances when reductions or approximations differ. For speed comparisons, hold output quality and timed scope fixed; see benchmarks.