PDB2PQR troubleshooting

When PDB2PQR fails to prepare a structure or produces unexpected output, this page covers the common failure modes — from PDB fetch errors and missing atoms to surprising protonation states, steric-clash resolution, force-field gaps for non-standard residues, and timeouts on large structures.

PDB2PQR troubleshooting

PDB ID not found

Symptom: "Could not fetch PDB structure" error.

Fixes:

• Verify the PDB ID is correct (four alphanumeric characters)
• Check that the structure exists on RCSB PDB
• Recently deposited structures may not be available yet. Upload the PDB file directly instead.

Missing atoms in output

Symptom: Output PQR has fewer atoms than expected, or warnings mention missing residues.

Causes:

• Disordered regions: Crystal structures often have missing density for flexible loops. PDB2PQR cannot model completely missing residues.
• Non-standard residues: Modified amino acids may lack force field parameters and get dropped.
• Ligand not included: PDB2PQR does not parameterize ligands — HETATM records without force-field parameters are dropped. Protonate the receptor here, then handle ligand parameterization with a dedicated cheminformatics tool.

Fix: Check the warnings array in the output for specific messages about dropped atoms.

Unexpected protonation states

Symptom: A residue is protonated/deprotonated contrary to expectation.

Explanation: PROPKA predicts pKa based on the local electrostatic environment. Buried residues, salt bridges, or hydrogen bond networks can shift pKa values significantly from model compound values.

Verification:

• Check the pKa table to see if the predicted value is near the target pH (borderline cases)
• Compare with experimental pKa data if available
• Visualize the residue environment to understand the electrostatic context

DEBUMP fails with steric clashes

Symptom: "Could not resolve steric clashes" warning.

Fixes:

• Set debump: false if you do not need clash resolution (some downstream tools handle this)
• The steric clash may indicate a genuine structural issue (crystal packing artifact, alternate conformations)
• Try processing a single chain with chain_ids to reduce complexity

Force field errors for non-standard residues

Symptom: "No parameters found for residue XXX" warning.

Explanation: Non-standard residues (selenomethionine, modified amino acids, ligands) may not be parameterized in the selected force field.

Fixes:

• Try a different force field (CHARMM has broader residue coverage for some modifications)
• Remove non-standard atoms from the structure before uploading it — PDB2PQR does not have a built-in flag for this
• For ligands, use dedicated parameterization tools and merge the parameters manually

Large structure takes too long

Symptom: Job exceeds timeout for structures with > 10,000 atoms.

Fixes:

• Process a single chain with chain_ids
• Enable remove_water: true to reduce atom count
• Disable hydrogen-bond optimization (optimize_hydrogen_bonds: false) for faster processing (less accurate hydrogen placement)

Getting help

If issues persist:

1. Check the job logs for specific warning messages
2. Validate your PDB file with the RCSB validation server
3. Describe the issue to Ivy

Read next