Common GROMACS Errors and How to Fix Them (LINCS Warnings, PBC and ‘Atom Not Found’)

Most GROMACS errors fall into three families: setup mismatches from pdb2gmx (atom or residue names the force field does not recognise), geometry problems (a box smaller than twice the cut-off), and a system blowing up (LINCS warnings, 1-4 interaction errors). The message names the symptom. The fix almost always sits upstream, in how you prepared the system.

The hardest part of your first molecular dynamics run is not the physics. It is a wall of red text that stops you at 11pm the night before a meeting with your supervisor. This troubleshooting guide from the StemSkills Lab team (10+ years in sequence and structural bioinformatics, drug discovery and design, and multiscale molecular modeling) maps the errors beginners actually hit to their real causes, so you can read the exact message, understand why it happened, and get the simulation running. For the full workflow these errors interrupt, start from our pillar guide on learning molecular dynamics with GROMACS.

What do GROMACS errors actually tell you?

They tell you where the run died, not why. That distinction saves hours. A LINCS warning is printed by the constraint algorithm, but the constraint algorithm is rarely the problem. The official GROMACS documentation is blunt about this in its Common errors when using GROMACS page: when a system is blowing up, “the constraints are usually the first thing to fail.” Constraints are the canary, not the gas leak.

So read every error in two steps. First, identify which stage printed it (gmx pdb2gmx, gmx grompp, or gmx mdrun). Second, ask what upstream decision produced it. Use this table as a triage sheet.

What causes LINCS warnings, and how do I fix them?

LINCS warnings mean atoms are moving so violently that the constraint solver cannot hold bond lengths fixed. LINCS itself is a well-tested algorithm, published by Hess, Bekker, Berendsen and Fraaije as LINCS: A Linear Constraint Solver for Molecular Simulations (Journal of Computational Chemistry, 1997, 18(12), 1463-1472). If it is failing, your system is unphysical.

The GROMACS terminology page lists the documented causes of blowing up. In student projects, these four account for most cases:

1. Energy minimisation was not thorough. A steric clash left in the structure produces an enormous force on step one.
2. The timestep is too large for the constraints in use. The dt default is 0.001 ps. If you jumped to 0.002 ps, your constraints setting must justify it.
3. Position restraints sit far from the actual coordinates. The restraint yanks the atom violently toward a position it was never near.
4. An isolated water molecule is trapped inside the protein or in a vacuum pocket.

Work the problem in that order. Re-minimise first. Then look at which atoms are named in the warning, because GROMACS tells you the atom pair, and open that region in a viewer to find the clash. Do not reach for -maxwarn. The documentation’s warning is direct: “Just because the -maxwarn option is available does not mean you should use it in the blind hope of your simulation working. It will undoubtedly blow up.”

Why does pdb2gmx say “not found in rtp entry”?

Because the atom names in your coordinate file do not match the names the force field expects. A real instance looks like Atom HG in residue SER 25 was not found in rtp entry SER with 11 atoms while sorting atoms. The residue building blocks live in the force field’s .rtp file, and pdb2gmx sorts your atoms against that list. Three causes explain nearly all of these:

• Hydrogen naming mismatch. Different sources name hydrogens differently. Let pdb2gmx rebuild them with gmx pdb2gmx -f protein.pdb -o processed.gro -water spce -ignh. The -ignh flag discards the hydrogens in your file and adds the correct ones.
• Atoms genuinely missing from the structure. Crystal structures often lack disordered side chains. Open the PDB file and search for REMARK 465 (missing residues) and REMARK 470 (missing atoms). These must be modelled back in with external software before pdb2gmx will accept the file.
• A terminal residue problem. If the N-terminus lacks hydrogens, the -ter option was probably not supplied or the wrong terminus type was chosen interactively.

Note the difference between the second cause and the other two. Renaming an atom is a five-second fix. Missing residues mean your structure is incomplete and needs modelling, which is a real preparation step, not a workaround.

What does “Residue ‘XXX’ not found in residue topology database” mean?

It means the force field you selected has no entry for that residue at all. The documentation states it plainly: the force field “does not have an entry in the residue topology database for XXX”, either because the database genuinely lacks the residue or because the name is different.

For students this is almost always a ligand, a cofactor, or an ion sitting in the HETATM records of a downloaded PDB file. Standard protein force fields do not carry parameters for your drug-like molecule. The fix is not to force pdb2gmx through it. Strip the ligand out, parameterise it separately, and include the resulting .itp in your topology.

Why does my protein look broken or drift out of the box?

This one is not an error at all, which is exactly why it confuses people. Your protein splitting across the box edge, drifting away from the centre, or appearing to leave the box entirely are expected consequences of periodic boundary conditions. GROMACS documents these as common visual artifacts users mistake for errors. Nothing is wrong with your simulation.

Fix the visualisation with gmx trjconv, in the documented order. Make molecules whole first, then remove jumps, then centre:

• gmx trjconv -s md.tpr -f md.xtc -o md_whole.xtc -pbc mol -ur compact makes molecules whole and uses a compact unit cell.
• gmx trjconv -s md.tpr -f md.xtc -o md_nojump.xtc -pbc nojump stops atoms teleporting across faces.
• Add -center to place your protein in the middle of the box for figures.

Order matters here. The manual notes that if the reference structure is not whole, using -pbc nojump will undo the earlier steps. Centring also shifts the system, which prevents a later -pbc nojump from working correctly. Run the steps in sequence, not all at once.

Why does GROMACS say my cut-off is longer than half the box?

Because an atom would interact with its own periodic image, which breaks the minimum image convention. The message reads: The cut-off length is longer than half the shortest box vector or longer than the smallest box diagonal element. Increase the box size or decrease rlist. That is not a formatting complaint. It is a physics violation, and the results would be meaningless.

The documented fix is to make the box at an absolute minimum twice the cut-off length in all three dimensions, or to reduce the cut-off. The rlist default is 1 nm, so a protein needs real clearance. Build the box with a distance to the edge, for example gmx editconf -f processed.gro -o boxed.gro -c -d 1.0 -bt cubic, and the box scales with your solute rather than to a guessed number.

What does “1-4 interaction not within cut-off” mean?

It means two atoms separated by three bonds have moved further apart than the cut-off, which should be geometrically impossible in an intact molecule. The documentation calls this out in capitals: “Some of your atoms have moved so two atoms separated by three bonds are separated by more than the cut-off distance. This is BAD. Most importantly, do not increase your cut-off!”

The instinct to raise the cut-off is exactly wrong. It hides the symptom while the molecule keeps flying apart. This error indicates very large velocities, which is the same blowing-up problem behind LINCS warnings, so treat it identically: go back to minimisation and equilibration.

Why did steepest descents stop before reaching Fmax?

You will often see that minimisation “converged to machine precision” without reaching the requested Fmax. This is usually fine. Steepest descents stops when a proposed step becomes too small to represent, or when the energy stops changing, whichever comes first. Given your starting configuration and settings, it has done what it can.

The emtol default is 10.0 kJ mol⁻¹ nm⁻¹, which is a strict target that a solvated protein with constraints will not always hit. Judge the result on whether the maximum force is low enough that the system will not explode in the first MD step, and on whether the potential energy is negative and stable. If minimisation genuinely stalls with a huge Fmax, suspect constraints or a clash rather than the minimiser. The Energy minimization section of the reference manual describes the algorithm and its stopping conditions.

What about charge and domain decomposition errors?

System has non-zero total charge from grompp usually means you have not added counter-ions yet, and gmx genion will neutralise the system. Read the number carefully, though. The documentation gives a useful diagnostic: if the charge “is not very close to an integer, then this indicates that there is a problem with the topology.” A charge of -8.000 is a missing-ions problem. A charge of -7.63 is a topology problem, and adding ions would only paper over it.

There is no domain decomposition for n ranks that is compatible with the given box and a minimum cell size of x nm means mdrun could not cut your box into enough valid pieces. As the manual puts it, it is “not possible to run a small simulation with large numbers of processors.” Ask for fewer ranks. A small test system on a laptop does not need 16 of them.

Frequently asked questions

Should I ever use -maxwarn to get past a grompp error?

Only when you know precisely which warning you are suppressing and why it is safe. Using it to push a failing system through is how you get a run that blows up hours later, after burning cluster time.

My simulation ran fine for 20 ns and then crashed with LINCS warnings. Why?

A late crash usually points to something that accumulated rather than a setup error, for instance a restraint fighting the dynamics, or a rare clash after a conformational change. Check the frames just before the crash in a viewer instead of restarting blindly.

Can I just switch force fields to make the rtp error disappear?

It may remove the message, but a force field is a scientific choice, not an error workaround. Switching changes your results and you will have to justify it in your methods section.

Is a broken-looking protein in VMD a failed simulation?

No. It is periodic boundary conditions doing their job. Post-process the trajectory with gmx trjconv -pbc mol before you judge or publish anything.

How do I know if my minimisation was good enough?

Look at the maximum force and the potential energy in the log. A stable negative potential energy and a force low enough to survive the first MD step matter more than hitting emtol exactly.

Where this fits in your training

Debugging GROMACS is a skill that compounds. Once you can read an error as a symptom of an upstream decision, the same reasoning transfers to docking, free energy calculations, and every other tool you will touch. If you are planning your progression from structure preparation through to production MD, our computational biology skills roadmap lays out the order that works, and the official GROMACS error page is worth bookmarking as your first reference for any message not covered here.