Common GROMACS errors and how to fix them (2026 edition)

Every error message on this page was produced with GROMACS 2026.3, either on a solvated Trp-cage miniprotein (PDB 1L2Y, 7,654 atoms) or on HIV-1 protease (PDB 1HSG). The errors were triggered deliberately so that the exact wording can be shown. Search this page for the first line of your error.

Two general rules come first, because they would prevent half of the questions on the GROMACS forum:

1. Read the first error, not the last line. grompp collects errors and warnings and then ends with There were N errors in input file(s) or Too many warnings. The useful information is above that line.
2. Do not reach for -maxwarn by reflex. grompp warnings are almost always about physics: a thermostat that gives the wrong ensemble, a barostat that will be integrated badly, or restraints that cause artefacts. -maxwarn is acceptable only for a specific warning that you have read, understood and can justify in your methods section. Never use it for “all of them”.

Many of the .mdp problems below can be caught before you run anything: paste the file into the mdp checker, which reports all the problems at once instead of one grompp run at a time.

pdb2gmx errors

Residue ‘XXX’ not found in residue topology database

Fatal error:
Residue 'MK1' not found in residue topology database

This is from running gmx pdb2gmx on the full 1HSG entry, which contains the inhibitor MK1. The residue topology database (aminoacids.rtp and friends in the force-field directory) only knows standard biopolymer residues, ions and water. pdb2gmx cannot parametrise a drug-like ligand. It is not meant to. The fix is to split the system:

• Run pdb2gmx on the protein only (grep -E '^(ATOM|TER)').
• Parametrise the ligand separately: CGenFF for CHARMM36, or GAFF2 with AM1-BCC charges through ACPYPE/antechamber for AMBER force fields.
• Combine the two in topol.top. The protein–ligand MD tutorial shows every step.

If the “unknown residue” is a standard residue with a non-standard name (HSD vs HISD vs HID, CYX, an N-methylated terminus), rename it to what your force field expects, or choose the protonation state interactively with -his.

Atom X in residue Y was not found in rtp entry / Missing atoms

These mean the structure is incomplete (missing side chains or loops) or its hydrogen names do not match the force field. Use -ignh to let pdb2gmx rebuild all hydrogens from its own naming. Missing heavy atoms must be modelled first (PDBFixer, Modeller, or the CHARMM-GUI PDB Reader). pdb2gmx will not build them, and -missing produces a broken topology.

grompp errors

Number of coordinates does not match topology

Fatal error:
number of coordinates in coordinate file (short.gro, 7653)
             does not match topology (../topol.top, 7654)

The [ molecules ] section at the end of topol.top must list the molecules in the same order and the same numbers as they appear in the coordinate file. The usual causes:

• You ran gmx solvate or gmx genion but the topology was not updated. Both tools update topol.top only if you pass it with -p.
• You added a ligand to the .gro file but not to [ molecules ], or the other way round.
• genion replaced waters with ions, but you edited the SOL count by hand.
• The order is wrong: the ligand comes after the protein in the .gro file but is listed after the water in the topology.

Compare tail -n 15 topol.top with the residue names in your .gro file. Do not “fix” the line counts by deleting atoms.

Cannot find position restraint file restraint.gro (option -r)

Fatal error:
Cannot find position restraint file restraint.gro (option -r).
From GROMACS-2018, you need to specify the position restraint coordinate files
explicitly to avoid mistakes, although you can still use the same file as you
specify for the -c option.

Your .mdp has define = -DPOSRES, which switches on the #ifdef POSRES block in the topology, so grompp needs reference coordinates for the restraints. Add -r em.gro (usually the same file as -c).

Group X referenced in the .mdp file was not found

Fatal error:
Group Protein_LIG referenced in the .mdp file was not found in the list of
index groups.
Group names must match either [moleculetype] names or custom index group
names, in which case you must supply an index file to the '-n' option

tc-grps, energygrps and the freeze and COM groups must name groups that exist. Without -n, only the default groups are available (System, Protein, Water, SOL, Ion, …). Make the combined group with gmx make_ndx (for example 1 | 13, then name 20 Protein_LIG) and pass -n index.ndx to every later grompp call. Alternatively, couple the whole system as one group: tc-grps = System is perfectly fine with the V-rescale thermostat.

With Verlet lists rcoulomb!=rvdw is not supported

ERROR 1 [file npt.mdp]:
  With Verlet lists rcoulomb!=rvdw is not supported (except for
  rcoulomb>rvdw with PME electrostatics)

This is common in files written for the old group scheme (for example rcoulomb = 1.0, rvdw = 1.2). With the Verlet scheme, set them equal. For CHARMM36 the GROMACS manual recommends 1.2 nm with vdw-modifier = force-switch and rvdw-switch = 1.0.

The group cutoff scheme has been removed

Fatal error:
The group cutoff scheme has been removed since GROMACS 2020. Please use the
Verlet cutoff scheme.

Delete cutoff-scheme = group (Verlet is the default) and recheck the cut-off settings. Old .mdp files that relied on the group scheme often also have the rcoulomb ≠ rvdw problem above.

Parameter “X” doubly defined

ERROR 1 [file md.mdp, line 57]:
  Parameter "rvdw_switch" doubly defined

grompp treats rvdw_switch and rvdw-switch as the same key, and a key may appear only once. This usually happens after pasting a block from another file. Search for both spellings.

Generating velocities is inconsistent with attempting to continue a previous run

ERROR: Generating velocities is inconsistent with attempting to continue a
previous run. Choose only one of gen-vel = yes and continuation = yes.

Choose one. The first dynamics stage after minimisation (usually NVT) generates velocities: gen-vel = yes, continuation = no. Every later stage continues from the previous checkpoint: gen-vel = no, continuation = yes, and pass -t previous.cpt to grompp.

Unknown left-hand ‘X’ in parameter file

WARNING 1 [file md.mdp, line 58]:
  Unknown left-hand 'nstxout_compresed' in parameter file

This is a typo (here compresed) or an option that no longer exists. It is reported as a warning, so it stops grompp at -maxwarn 0, but people often silence it with -maxwarn. Never ignore it. The setting you think you made has no effect. Renamed options (nstxtcout → nstxout-compressed, xtc-grps → compressed-x-grps) are still translated automatically, with a “Replacing old mdp entry” message. Options removed altogether need to be dropped from the file.

grompp warnings that are really about physics

The Berendsen thermostat / barostat

WARNING 1:
  The Berendsen thermostat does not generate the correct kinetic energy
  distribution, and should not be used for new production simulations (in
  our opinion). We would recommend the V-rescale thermostat.

WARNING 1:
  The Berendsen barostat does not generate any strictly correct ensemble,
  and should not be used for new production simulations (in our opinion).
  We recommend using the C-rescale barostat instead.

Older tutorials used Berendsen coupling for equilibration because it is robust. Its modern replacements are just as robust and give correct ensembles: V-rescale (Bussi et al., 2007) for temperature and C-rescale (Bernetti & Bussi, 2020) for pressure. Switch to them for every stage, including equilibration. Then there is nothing to justify with -maxwarn.

tau-p should be at least N times larger than nstpcouple*dt

WARNING 1:
  For proper integration of the Parrinello-Rahman barostat, tau-p (2)
  should be at least 200 times larger than nstpcouple*dt (0.02)

Each coupling algorithm needs a minimum number of integration steps per coupling period: 25 for C-rescale and Berendsen, 200 for Parrinello-Rahman (MTTK too). Here nstpcouple = 10 and dt = 0.002 give 0.02 ps per coupling step, and 2 ps / 0.02 ps = 100 < 200. Fixes: set nstpcouple = -1 (the default, which lets grompp choose a valid value) or a smaller value such as 5, or increase tau-p. The same warning appears for C-rescale if, for example, tau-p = 1 and nstpcouple = 50.

Pressure coupling with absolute position restraints

WARNING 1:
  You are using pressure coupling with absolute position restraints, this
  will give artifacts. Use the refcoord_scaling option.

During restrained NPT equilibration, the restraint reference positions must scale with the box. Add refcoord-scaling = com.

Removing the rotation around the center of mass in a periodic system

WARNING 1:
  Removing the rotation around the center of mass in a periodic system,
  this can lead to artifacts. Only use this on a single (cluster of)
  molecules. This cluster should not cross periodic boundaries.

comm-mode = Angular is meant for a molecule in vacuum, not for a solvated periodic box. Use comm-mode = Linear (the default).

Parrinello-Rahman with position restraints

NOTE 1 [file topol.top, line 2996]:
  You are combining position restraints with Parrinello-Rahman pressure
  coupling, which can lead to instabilities. If you really want to combine
  position restraints with pressure coupling, we suggest to use C-rescale
  pressure coupling instead.

This is only a NOTE, but take it seriously. Use C-rescale for restrained NPT equilibration. C-rescale is also a good choice for production, because it gives correct volume fluctuations. Parrinello-Rahman is fine for unrestrained production once the box has relaxed.

You will usually also see this NOTE during restrained equilibration. It is harmless there:

  Removing center of mass motion in the presence of position restraints
  might cause artifacts. When you are using position restraints to
  equilibrate a macro-molecule, the artifacts are usually negligible.

The one legitimate -maxwarn: preparing genion’s input

WARNING 1 [file topol.top, line 58]:
  You are using Ewald electrostatics in a system with net charge. This can
  lead to severe artifacts, such as ions moving into regions with low
  dielectric, due to the uniform background charge. We suggest to
  neutralize your system with counter ions, possibly in combination with a
  physiological salt concentration.

Here this came from HIV-1 protease (net charge +4) in water. It appears when you build the .tpr that gmx genion needs, before ions exist. In this one case -maxwarn 1 is justified, because the next command (genion -neutral) fixes exactly this problem. If the warning appears at any later stage, your system is still charged: check the [ molecules ] counts and the ligand’s net charge.

mdrun errors

LINCS / SETTLE warnings and “particles moved more than”

Typical messages are LINCS WARNING: relative constraint deviation after LINCS, SETTLE … can not be settled, and X particles communicated to PME rank Y are more than 2/3 times the cut-off out of the domain decomposition cell. They all mean the same thing: the system blew up. Atoms moved too far in one step because of huge forces. The message tells you where it blew up (the atom numbers), not why. Check, in order:

1. Did energy minimisation converge? Look at Fmax in the EM log. It should be below emtol (commonly 1000 kJ mol⁻¹ nm⁻¹). If minimisation stopped with “Fmax > emtol” after “converged to machine precision”, find the atom with the maximum force (the log names it) and inspect it. Usually this is a clash, a misplaced ligand, or a bad ligand topology.
2. Is the ligand topology right? Wrong bond orders, a missing hydrogen or a wrong charge can all cause a crash in the first picoseconds. Visualise the ligand after EM. Distorted rings are a giveaway.
3. Is the time step compatible with your constraints? 2 fs needs constraints = h-bonds. 4 fs needs hydrogen mass repartitioning (mass-repartition-factor = 3) in addition.
4. Was the system equilibrated in stages? Start with NVT using restraints and generated velocities, then NPT with restraints, then unrestrained production. Skipping straight to unrestrained NPT from a minimised structure is a common cause of crashes.
5. Is the atom number inside a ligand or at a periodic boundary? Use gmx trjconv -pbc mol to view the structure correctly. A molecule split across the box is a display artefact, not a crash cause.

Can not do energy minimization with Shake, use Lincs

Fatal error:
Can not do energy minimization with Shake, use Lincs

grompp accepts constraint-algorithm = SHAKE with integrator = steep, but mdrun refuses it. Use LINCS (the default), or constraints = none for minimisation.

The cut-off length is longer than half the shortest box vector

The box is too small for the cut-off. With a 1.2 nm cut-off, every box dimension must be above 2.4 nm, and in practice much more. Solvate with at least 1.0 nm between the solute and the box edge (gmx editconf -d 1.0). If the error appears during NPT, the box is shrinking too much, usually because the system was badly equilibrated or contains a vacuum bubble.

A checklist before you submit a job

• Run grompp with -maxwarn 0 and read every NOTE.
• Make sure each stage uses the right -c, -r and -t inputs, and that continuation matches.
• Check tc-grps, tau-t and ref-t counts, and the index file.
• Check that nsteps × dt is the length you intend. The mdp checker prints it, together with the output size.
• Do a 10-picosecond test run and look at it before you queue 500 ns.

References

1. GROMACS 2026 documentation: Common errors when using GROMACS and mdp options.
2. Bussi G, Donadio D, Parrinello M. Canonical sampling through velocity rescaling. J Chem Phys 2007;126:014101. doi:10.1063/1.2408420
3. Bernetti M, Bussi G. Pressure control using stochastic cell rescaling. J Chem Phys 2020;153:114107. doi:10.1063/5.0020514
4. Hess B. P-LINCS: A parallel linear constraint solver for molecular simulation. J Chem Theory Comput 2008;4:116–122. doi:10.1021/ct700200b
5. Lemkul JA. From proteins to perturbed Hamiltonians: A suite of tutorials for the GROMACS-2018 molecular simulation package. Living J Comp Mol Sci 2019;1:5068. doi:10.33011/livecoms.1.1.5068