PDB Defect Atlas
A verified catalogue of structural defects in PDB files that cause failures in downstream molecular docking, simulation, and antibody modeling tools — with named check IDs, severity, and fixes. Sourced from confirmed failures and tool documentation.
How to read this page
- Check ID — a machine-readable slug for each defect, matching the named check in StructSure's pipeline engine. Use it in bug reports and scripts.
- Severity — Blocking means the tool fails or silently produces wrong output. Warning means degraded results. Info is a known quirk worth knowing.
- Fix — a pill links to a StructSure pipeline operation that addresses it. Italic text is an upstream recommendation.
- Source badges: Verified = confirmed in a real failing file. Docs = from tool documentation.
ColabDock
VerifiedAlphaFold2-based diffusion docking served via NeuroSnap. Expects one antigen chain and one VHH/antibody chain (chain H). All failures below are confirmed from real submissions; the platform returns only a generic error: "Please ensure your restraints, chain IDs, and structure are valid."
| Check ID | Severity | Defect & Evidence | Fix |
|---|---|---|---|
| COLABDOCK_CHAIN_H | Blocking | VHH/nanobody is not on chain H. ColabDock hard-requires the antibody on chain H. ColabFold and ESMFold output single-chain folds as chain A; merge scripts avoiding a chain ID collision typically bump the VHH to chain B, not H. | chain_order option in docking-ready export forces explicit ordering, or rename chain → H before submitting. |
| COLABDOCK_TER_RECORDS | Blocking | PDB contains TER records. ColabDock's parser treats TER as end-of-input and stops reading, silently dropping all subsequent chains including the VHH. Confirmed by direct file comparison: identical coordinate data with TER records failed; same file without TER succeeded. Note: this is the opposite of AMBER, which fails without TER records. | postprocess_pdb_text strips TER when
target_service=colabdock. |
| COLABDOCK_EXPLICIT_H | Blocking | Explicit hydrogen (H/D) atoms present. ColabDock requires heavy atoms only; its internal validation aborts on H-containing inputs. | strip_hydrogens — auto-applied for
target_service=colabdock. |
| COLABDOCK_RESIDUE_NUMBERING | Blocking | Residue numbering does not start at 1 in one or more chains. Common in VHH domains extracted from a full IgG model where framework residues begin at 139. Confirmed failure. | renumber_residues — auto-applied for
target_service=colabdock. |
| COLABDOCK_PLDDT_SCALE | Blocking | pLDDT stored as a 0–1 fraction in the B-factor column instead of 0–100. ESMFold's
web server and API inconsistently output either scale depending on version. ColabDock
uses B-factors as per-residue confidence weights; near-zero values cause an internal
abort. Diagnostic: max(B-factor) ≤ 1.0 → fractional scale. Fixed file had
B-factors 43–97 (mean 85.6) and succeeded. |
Multiply B-factors by 100 before submitting ESMFold outputs. Check max B-factor in the VHH chain before every submission. |
| COLABDOCK_IMPOSSIBLE_CA | Blocking | Consecutive Cα–Cα distances below 3.4 Å (correct ≈ 3.8 Å). Found in VHH CDR3 loops with a triple-proline (PPP) run paired with a non-canonical CDR1–CDR3 disulfide at Cys97 instead of the standard Cys92. AF2 cannot satisfy both constraints simultaneously. Distances of 2.87–2.97 Å observed in confirmed failing files. A VHH with standard Cys23–Cys92 geometry had zero bad distances and succeeded. | Try AF2 rank 2–5 models. For intractable PPP cases, targeted CDR3 loop refinement with MODELLER or PyRosetta can resolve geometry without moving the framework. |
| COLABDOCK_SIDECHAIN_TRUNCATION | Blocking | Residues truncated to backbone + Cβ only; sidechain atoms beyond CB are absent. Characteristic output of NanoNet, which is a backbone/Cβ predictor by design. 95 of 116 VHH residues were missing sidechains in a confirmed failure — ColabDock's validation aborted. | Replace NanoNet with a full-atom predictor: NanoBodyBuilder2 (opig.stats.ox.ac.uk/sabpred), ColabFold, or ESMFold full-atom. NanoNet was designed for speed, not docking inputs. |
| COLABDOCK_MULTI_CHAIN_ANTIGEN | Blocking | Antigen consists of more than one chain (e.g. Fc homodimer chains A and C). ColabDock's architecture processes only a single antigen chain; multi-chain antigens either silently drop the second chain or exhaust GPU memory. Hard architectural limitation — not a fixable file defect. | Dock against the monomer. Post-filter results using the buried homodimer interface residues (Cα atoms within 8 Å of the second chain in the assembled dimer). Poses contacting buried residues are biologically inaccessible in the intact protein. |
| COLABDOCK_SERIAL_NUMBERS | Warning | Non-sequential atom serial numbers after chain reordering or residue renumbering. Breaks parsers that use the serial column as an index. | renumber_atom_serials — auto-applied after any reorder or renumber operation. |
| COLABDOCK_OXT | Warning | OXT terminal oxygen atoms present at chain C-terminus. | remove_oxt — auto-applied for
target_service=colabdock. |
| COLABDOCK_ATOM_ALIGNMENT | Info | PDB standard requires right-padded atom names ( N ), but ColabDock has been
observed to accept left-aligned names (N ) and reject standard formatting
in some contexts. Observed in a direct file comparison with identical coordinates and
different formatting conventions. |
Quirk of ColabDock's parser — no general action required. If submitting a file generated by PyMOL or BioPython PDBIO and it fails for no other apparent reason, left-aligning atom names is a low-effort diagnostic step. |
AMBER / tleap + pdb4amber
Docstleap requires strict residue naming to match its force-field library. pdb4amber automates most of these conversions but understanding what it does prevents silent errors. The key inversion from ColabDock: AMBER requires TER records; ColabDock fails on them.
| Check ID | Severity | Defect | Fix |
|---|---|---|---|
| AMBER_HIS_NAMING | Blocking | Histidine residues named HIS. AMBER requires protonation-state-specific names: HID (Nδ), HIE (Nε), HIP (both). Generic HIS causes incorrect parameters or tleap failure. | pdb4amber or reduce.py assigns protonation states and renames. Use PropKa to predict states at target pH. |
| AMBER_CYS_DISULFIDE | Blocking | Disulfide-bonded cysteines named CYS. AMBER requires CYX with explicit
bond commands in the tleap input specifying the SG–SG pair. Without
this, tleap adds H to both SG atoms as free thiols and breaks the disulfide geometry. |
pdb4amber detects CYS pairs within 2.5 Å and renames to CYX. Verify SG–SG distances first — distorted geometry can cause false positives. |
| AMBER_EXISTING_H | Blocking | Pre-existing hydrogen atoms. Atom names rarely match AMBER's internal library
(e.g. 1HB vs HB2), causing tleap to add duplicate atoms or
error with "Could not find atom." |
strip_hydrogens before passing to tleap; let tleap or reduce add them with correct naming. |
| AMBER_ALTLOC | Blocking | Alternate location (altLoc) indicators present. tleap cannot handle multiple conformers. | resolve_altlocs — keeps highest-occupancy conformer. |
| AMBER_TER_MISSING | Blocking | Missing TER records at chain ends or internal backbone gaps. tleap bonds across gaps without TER, creating impossible covalent connections that corrupt the topology. The most common silent error in AMBER preparation, and the inverse of the ColabDock TER problem above. | postprocess_pdb_text adds TER at every chain boundary. For internal gaps, explicit AMBER input scripting is needed. |
| AMBER_LIGAND_PARAM | Blocking | Ligands or non-standard residues present without GAFF/GAFF2 parameters. tleap cannot assign force-field parameters to unrecognized residues and exits. | Run antechamber + parmchk2 to generate .frcmod and .mol2 per ligand. Or remove ligands if they're not part of the simulation target. |
| AMBER_WATER_NAMING | Warning | Water molecules named HOH or H2O. AMBER requires WAT. tleap may skip or fail on crystallographic waters with incorrect names. | Rename HOH → WAT, or remove crystallographic waters and let tleap solvate with an explicit water box. |
OpenMM / PDBFixer
DocsPDBFixer is the standard preprocessing step for OpenMM simulations and handles many issues automatically. Key limitations: long loops are not modeled, and very large systems prefer mmCIF input.
| Check ID | Severity | Defect | Fix |
|---|---|---|---|
| OPENMM_NONSTANDARD | Blocking | Non-standard residues present (MSE, HID, phosphoSer, etc.). OpenMM requires standard names to match its force-field topology library. Unknown residues must be replaced or removed. | PDBFixer's replaceNonstandardResidues() handles common substitutions
(MSE→MET). Rare residues require manual parameterization. |
| OPENMM_DISULFIDE | Warning | Disulfide bonds inferred by proximity rather than CONECT records. Distorted SG–SG geometry (expected 2.0–2.1 Å) from a poor model can cause missed or false assignments. | Verify SG–SG distances before running. Add CONECT records explicitly if proximity detection is unreliable for your structure. |
| OPENMM_LONG_GAPS | Warning | Backbone gaps longer than ~5 residues. PDBFixer adds short missing loops but skips long ones, leaving a broken chain. | Model missing loops upstream (Modeller, RoseTTAFold, or AF2 with a full-sequence input). StructSure's quality screen reports gap location and size. |
| OPENMM_LARGE_SYSTEM | Info | Very large systems (>100,000 atoms) can exceed PDB format's 5-digit serial limit. mmCIF avoids column-width parsing issues at this scale. | Use mmCIF input for large assemblies. PDBFixer accepts both formats. |
HADDOCK
DocsThe leading data-driven docking server with ambiguous interaction restraint (AIR) support. The pdb-tools suite was built for HADDOCK preparation and is a useful standalone checklist. Entries from documentation; direct failure testing was not possible.
| Check ID | Severity | Defect | Fix |
|---|---|---|---|
| HADDOCK_INSERTION_CODES | Blocking | Insertion codes in residue numbering (82A, 82B, 82C from Kabat/Chothia/IMGT antibody numbering). HADDOCK's CNS backend cannot parse insertion codes. Sequential renumbering resolves it but breaks CDR position annotations — a mapping file is essential. | remove_insertion_codes + sequential renumber. Emit a scheme→sequential mapping to preserve CDR annotations. |
| HADDOCK_CHAIN_IDS | Blocking | Duplicate chain IDs across partners, or a single chain spanning both molecules. Each docking partner must have a distinct chain identifier. | chain_order / chain renaming options in docking-ready export. |
| HADDOCK_MULTI_MODEL | Blocking | NMR-style multi-MODEL records. HADDOCK requires a single model. | Extract MODEL 1 with pdb-tools ( |
| HADDOCK_ALTLOC | Blocking | Alternate location indicators present. | resolve_altlocs |
Rosetta (RosettaDock, SnugDock, FastRelax)
DocsRosetta applications share a common PDB reader. StructSure's SnugDock Export recipe handles chain renaming to H/L/A convention automatically.
| Check ID | Severity | Defect | Fix |
|---|---|---|---|
| ROSETTA_HETATM | Blocking | HETATM records for non-standard residues or ligands without Rosetta params files. Applications silently skip or exit, depending on flags used. | StructSure removes HETATM by default in docking-ready export. To keep a ligand,
generate .params with Rosetta's molfile_to_params. |
| ROSETTA_ZERO_OCC | Warning | Zero-occupancy atoms. May be included in scoring, skewing energy calculations. | Remove zero-occupancy atoms via pdb-tools or during altLoc
resolution. Rosetta flag |
| ROSETTA_RELAX | Info | Structure not energy-minimized before scoring or docking. Rosetta expects a FastRelax step before dock scoring; clashes inflate energy and produce unreliable ΔΔG estimates. | StructSure's Complex Relax & Validate uses OpenMM/AMBER14 implicit-solvent minimization as a substitute for FastRelax. For Rosetta-specific scoring, run FastRelax with the intended score function. |
AutoDock Vina / ADFR
DocsAutoDock Vina requires PDBQT-format inputs, not raw PDB. Conversion via prepare_receptor (ADFR Suite) or Meeko enforces most requirements automatically.
| Check ID | Severity | Defect | Fix |
|---|---|---|---|
| VINA_PDBQT_FORMAT | Blocking | Receptor is in PDB format, not PDBQT. PDBQT adds Gasteiger partial charges and AutoDock atom types. Vina cannot read plain PDB as receptor input. | Convert with |
| VINA_NONPOLAR_H | Blocking | Non-polar hydrogens present. Vina uses a united-atom model; non-polar H atoms are merged into their heavy-atom parent during conversion. Explicit non-polar H in the PDBQT inflate receptor size and corrupt scoring. | prepare_receptor removes non-polar H automatically. Polar H (NH, OH, SH) are retained. |
| VINA_ALTLOC | Blocking | Alternate location records. prepare_receptor cannot handle altlocs and produces a malformed PDBQT. | resolve_altlocs before conversion. |
PRODIGY (binding affinity prediction)
DocsPRODIGY estimates binding ΔG from inter-chain contacts. It is sensitive to chain identity and interface completeness.
| Check ID | Severity | Defect | Fix |
|---|---|---|---|
| PRODIGY_CHAIN_IDS | Blocking | Partners share a chain ID, or the complex is written as a single chain. PRODIGY requires distinct chain IDs per partner to count inter-chain contacts correctly. | Ensure each partner has a unique chain ID before running. Use StructSure's chain renaming when preparing a merged complex. |
| PRODIGY_NONSTANDARD | Warning | Non-standard residues at or near the interface. PRODIGY's contact scoring uses standard residue types; non-standard residues may be skipped, underestimating the buried interface area. | Remove or replace non-standard residues before running affinity prediction. |
| PRODIGY_INTERFACE_GAPS | Warning | Backbone gaps at the binding interface. Missing residues that contribute contacts reduce observed interface area and underestimate affinity. | Model missing interface loops upstream. StructSure's quality screen reports gap location and size. |
Antibody-specific (all tools)
Verified DocsAntibody and VHH/nanobody structures carry numbering schemes and geometry conventions from crystallography that systematically conflict with docking software requirements. These are intentional annotations, not errors — they require translation.
| Check ID | Severity | Defect | Fix |
|---|---|---|---|
| AB_SCHEME_NUMBERING | Blocking | Kabat, Chothia, or IMGT scheme numbering carries insertion codes (82A, 82B, 82C; 27A–27F; 100A–100K in long CDR3 loops). Breaks HADDOCK's CNS backend, confuses sequential residue lookup in most parsers, and prevents correct restraint specification. Sequential renumbering resolves parsing but loses CDR loop positions unless a mapping file is kept. | remove_insertion_codes + sequential renumber, with a scheme_position → sequential mapping output. This is StructSure's highest-impact antibody-specific feature. |
| AB_VHH_CHAIN_ID | Blocking | VHH chain has a wrong ID for the target tool: ColabDock needs H, SnugDock needs H (heavy) + L (light), HADDOCK needs any distinct pair. Fold predictors always output single-domain VHH as chain A; merge scripts typically bump it to B to avoid an ID collision. Neither A nor B is H. | chain_order for explicit ordering; SnugDock Export recipe for automatic H/L/A renaming. |
| AB_PREDICTOR_BACKBONE_ONLY | Blocking | Structure from a backbone-only predictor (NanoNet, ESMFold backbone mode) lacks sidechain atoms beyond Cβ. All docking tools require full-atom structures. Confirmed: 95 of 116 VHH residues truncated to Cβ caused ColabDock to abort. | Use a full-atom predictor: NanoBodyBuilder2, ColabFold (AlphaFold2), or ESMFold full-atom. NanoNet is designed for speed, not docking. |
| AB_PPP_GEOMETRY | Blocking | Triple-proline (PPP) runs in CDR3 paired with a non-canonical CDR1–CDR3 disulfide (Cys97 vs. standard Cys92) produce impossible Cα–Cα distances (2.87–2.97 Å; expected 3.8 Å) in AF2 predictions. All five AF2 ranking models show the same failure because it is sequence-driven, not a modeling artifact of a single rank. | Try AF2 rank 2–5 models as a first step. For persistent cases, targeted CDR3 loop refinement with MODELLER or PyRosetta can resolve geometry while holding the framework fixed. VHHs with standard Cys23–Cys92 are not affected. |
| AB_PLDDT_BFACTOR | Blocking | pLDDT confidence in B-factor column stored as 0–1 fraction instead of 0–100 scale. ESMFold's API and web server produce inconsistent scales across versions. Tools using B-factors as confidence weights (ColabDock confirmed) abort when values are near zero everywhere. | Diagnostic: |
| AB_RENUMBER_MAP | Info | After sequential renumbering to satisfy docking tool requirements, CDR loop positions (CDR1–3, H1–3, L1–3) can no longer be identified by scheme position numbers. Downstream contact mapping and epitope annotation require a translation table. | StructSure's renumber operation emits a scheme→sequential mapping on request. Planned as a standard output in the antibody docking workflow. |
Contributing to this atlas
This is a living document. If you have encountered a PDB defect that caused a failure in a docking, simulation, or structure analysis tool — particularly a verified failure with a specific file or error message — we want to add it.
Email tailwindresearch@agentmail.to with a description of the defect, the tool it affected, and whether the failure was silent (wrong result) or explicit (error). Sharing the file or error output lets us mark the entry as Verified rather than Docs.
Each defect in this atlas corresponds to a named check in StructSure's pipeline engine. Adding a defect here is the first step to automating its detection.
Fix these defects automatically
Upload a PDB file and select your target docking tool. StructSure applies the right checks for that tool's requirements.