---
title: PDB2PQR troubleshooting
description: 'Fix PDB2PQR runs: dropped HETATM ligands and non-standard residues, surprising PROPKA pKa values, DEBUMP clash failures, and timeouts above 10,000 atoms.'
tags:
  - pdb2pqr
  - troubleshooting
---

When [PDB2PQR](/docs/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](https://www.rcsb.org/)
- 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](https://validate-rcsb.wwpdb.org/)
3. Describe the issue to Ivy

## Read next