# Diagnose automatic registration failures in 3D Slicer (BRAINS / Elastix)
Use this when an automatic registration (General Registration (BRAINS),
General Registration (Elastix), or BRAINSFit/Elastix under the hood) reports
"completed with error", crashes, hangs, or produces a wrong result. Registration
runs as a command-line module, so the GUI stays responsive while it works — the
evidence is in the **Error Log** (View / Error Log), not in the status message
alone. Open it and scroll to the bottom: you will see the `commandline` entry
with the arguments passed to the algorithm and the algorithm's own output.
## 1. "Completed with error" — check the inputs before anything else
Per the official registration FAQ, the most common failures are wrong or
inconsistent inputs. Verify all of these:
1. Both a **fixed** and a **moving** image are selected.
2. An **output** is selected (output transform and/or output volume). Registering
without an output target goes nowhere.
3. The two images **overlap** — can you see both in the slice views? If not,
recenter first (the FAQ's "Manual Recenter" step) and rerun with an
initializer.
4. Input consistency: General Registration (BRAINS) errors if you check a
**BSpline registration phase without selecting a BSpline output
transform**, or request masking without providing masking inputs/outputs.
If the inputs check out, read the Error Log's `commandline`/`standard output`
entries for the algorithm's own error — input-argument problems are reported
there.
## 2. Registration "succeeds" but the result is wrong or unchanged
Automatic intensity-based registration only converges from a reasonable start.
The documented rule of thumb from core developers: the initial error must be
within **5–10 mm translation and 5 degrees rotation**. A grossly misaligned
pair (e.g. a 180° flip) will never converge. Fix:
- Run a **landmark-based registration first** to get a rough alignment, then
feed that transform in as the initial transform of the automatic registration.
- Center-of-gravity / moments-based initializers handle pure translation
automatically when the physical extents are similar, but they cannot fix
large rotation errors.
## 3. You are registering binary images (labelmaps, segmentations)
Intensity-based registration **cannot align binary images**. Convert first:
run a DistanceMap filter from the **Simple Filters** module on both images and
register the resulting distance maps instead of the binary masks.
## 4. Elastix: `Command 'elastix' returned non-zero exit status 3221225477`
Exit status 3221225477 is 0xC0000005 — an **access violation**; the elastix
binary crashed rather than failing cleanly. The Error Log shows the full
command line the SlicerElastix module used (input `.mha` files under a temp
directory like a per-run temp folder under the user profile (`AppData/Local/Temp/Slicer/Elastix/[timestamp]/` on Windows),
parameter files such as `Par0000affine.txt` and `Par0000bspline.txt` from the
extension's `Resources/RegistrationParameters`). Triage:
1. Simplify the pipeline: run a **single rigid/affine stage** first. If affine
works but the multi-stage run crashes, the bspline stage or a parameter
file is the culprit.
2. Read the tail of the elastix log (the Error Log reproduces the algorithm
output): crashes right after "Reading images" point at the input volumes;
crashes mid-resolution point at memory or the parameter set.
3. Reproduce elastix **outside** Slicer on the same temp inputs if you need to
isolate whether the crash is the binary or the data.
Warnings like `The parameter "UseDirectionCosines" ... does not exist at all`
are informational (elastix ≥ 4.8 defaults it to true) — do not chase them as
the cause.
## 5. It hangs instead of failing
Registration is a separate process; the Slicer GUI stays usable, so a "hang"
is often just a long computation (bspline on large volumes, multi-threaded).
Before killing it, check the Error Log for progress output and Task Manager /
Activity Monitor for CPU activity on the CLI process. If CPU is idle and no
log output appears for many minutes, kill the process and treat it as case 1
or 4.
## Quick triage checklist
1. Error Log → `commandline` entry: capture the exact failure line.
2. Inputs: fixed + moving + output selected; images overlap; BRAINS phase /
transform-type / masking consistency (section 1).
3. Wrong result: initial alignment within 5–10 mm / 5°? If not, landmark
initialization first (section 2).
4. Binary inputs: distance maps, not masks (section 3).
5. Elastix 3221225477: crashed binary — simplify to single affine stage, read
the log tail (section 4).