---
title: MM-GBSA troubleshooting
description: >-
  Resolve common MM-GBSA force field, parameterization, and energy convergence
  issues.
tags:
  - mmgbsa
  - troubleshooting
---

Use this page to diagnose the failures you hit while running [MM-GBSA](/docs/mmgbsa) — ligand parameterization errors, unreasonable binding energies, missing atoms, protonation-state problems, minimization convergence, long runtimes, and per-residue anomalies. Getting inputs prepared correctly heads off most of them.

## Common issues and fixes

MM-GBSA combines molecular mechanics force fields with implicit solvation to estimate binding free energies. Understanding common issues helps you prepare inputs correctly and interpret results appropriately.

## Ligand parameterization failures

- **Unsupported elements**: MM-GBSA supports C, H, N, O, S, P, F, Cl, Br, I. Metal-containing ligands (e.g., Zn, Fe, Ru, Pt) are not supported by standard GAFF2 parameterization
- **Unusual functional groups**: Exotic moieties (e.g., boronates, silicon-containing groups, phosphonates) may lack force field parameters. The tool always parameterizes with AMBER14/GAFF2 — there's no alternate force field to switch to
- **Charge calculation failure**: AM1-BCC charge assignment can fail for highly charged or large ligands. Ensure formal charges are specified correctly in the input SDF
- **Valence errors**: Check that all atoms in the ligand have correct valence; over-coordinated or under-coordinated atoms cause parameterization errors

## Unreasonable binding energies

- **Extremely negative values** (< -25 kcal/mol): Usually indicates a parameterization artifact, steric clash relief during minimization, or incorrect protonation state. Check the input complex geometry
- **Positive binding energy**: Indicates the ligand is predicted to be more stable in solution than in the complex. This can happen if the docked pose has bad contacts, the ligand is partially solvent-exposed, or protonation states create charge-charge repulsion
- **All poses rank similarly**: If DeltaG_bind values differ by less than 1 kcal/mol across very different poses, the energy landscape may be flat; consider longer minimization or MD-based MM-GBSA

## Missing atoms or incomplete residues

- Ensure all heavy atoms are present in binding site residues; missing side-chain atoms cause topology errors
- Rebuild missing loops before submission, especially if they are near the binding site
- Remove alternate conformations (keep only the A conformation) to avoid duplicate atom errors
- Check for zero-occupancy atoms that may need to be removed or set to full occupancy

## Protonation state issues

- Histidine protonation is critical: HID (delta-protonated), HIE (epsilon-protonated), or HIP (doubly protonated) can change electrostatic binding energy by several kcal/mol
- Asp and Glu near the binding site may be protonated at low pH; if your experiment is at non-physiological pH, adjust protonation manually
- Cysteine residues forming disulfide bonds must be correctly assigned; free Cys near the ligand may need special attention
- Ligand protonation at pH 7.4 is assigned automatically; verify the ionization state matches your experimental conditions

## Minimization convergence issues

- The tool exposes a single `minimize_complex` on/off toggle — there's no step count, tolerance, or algorithm choice to tune. If minimization does not converge, the underlying issue is usually the input pose
- Very large initial steric clashes (from poor docking poses) are the most common cause; re-dock or manually adjust the pose before submitting
- If clashes persist, resubmit with `minimize_complex: false` to see the unminimized energy and confirm the clash is the source of the anomaly

## Long runtimes or timeouts

- Reduce the number of poses being scored (score top 1 instead of all)
- For large proteins (>500 residues), runtimes increase due to the GB solvation calculation
- Verify GPU availability; CPU fallback is 10-50x slower
- If multiple ligands need scoring, submit as separate jobs for parallelization

## Inconsistent rankings between solvent models

- The force field is fixed at AMBER14, but `solvent_model` (`gb_obc2`, `gb_obc1`, `gb_hct`) can give different absolute energies and occasionally different rankings
- This is expected behavior; choose one solvent model and use it consistently across a compound series
- `gb_obc2` is the recommended default for protein-small molecule systems
- If rankings are inconsistent, the binding energy differences may be within the method's uncertainty (2-3 kcal/mol)

## Per-residue decomposition anomalies

- Very large per-residue contributions (> 10 kcal/mol) from a single residue may indicate a charge assignment or parameterization issue
- Check that catalytic residues (Asp, Glu, His) have correct protonation states
- Metal-coordinating residues may show artifacts if metals are present but not parameterized
- Missing residues near the binding site can redistribute energy to neighboring residues

## Still stuck?

- Provide the job ID, force field, solvent model, and input file format
- Include any error messages from the parameterization or minimization phases
- Note whether the issue is with submission, calculation, or result interpretation
- Share the ligand SMILES and protein PDB ID (or source job) for reproducing the issue

## Read next