PDB Search troubleshooting

When PDB Search returns no results, download fails, or a structure isn't what you expected, this page covers the common failure modes — from empty searches and invalid PDB IDs to low-resolution structures, missing ligands, and file-parsing issues.

Common issues and fixes

PDB Search uses the RCSB Search and Data APIs. Most issues stem from query construction, PDB ID format, or structure quality expectations.

Empty or zero search results

• Overly specific query: Simplify your search terms. For example, "EGFR kinase domain T790M mutant with erlotinib" may be too specific. Try "EGFR erlotinib" instead.
• Organism name spelling: Use standard scientific names. "Human" is understood, but "Homo sapiens" is more precise. Some searches work better with the common name included alongside the protein name.
• Method-specific searches: If searching for cryo-EM structures, note that cryo-EM coverage is growing but still limited compared to X-ray. Broaden to all methods if results are sparse.
• Recently deposited structures: New PDB entries may take a few days to be indexed by the RCSB Search API after release.

PDB Download errors

• Invalid PDB ID format: PDB IDs must be exactly 4 characters (one digit followed by three alphanumeric characters). Common mistakes include using UniProt accessions (6+ characters) or NCBI structure IDs.
• Obsolete entries: Some PDB entries have been superseded by updated depositions. The RCSB website shows the replacement entry ID. Try the superseding PDB ID.
• Large file sizes: Very large structures (ribosomes, virus capsids) can produce files of 10+ MB. This may cause slow responses but should complete successfully.
• Format issues: If downstream tools have trouble reading the downloaded file, try switching between PDB and CIF formats. Some tools only accept one format.

Low-resolution or poor-quality structures

• Resolution selection: Search results are sorted by relevance, not resolution. You may need to manually inspect resolution values and select the best structure. Include "high resolution" in your search query to prioritize.
• Multiple structures available: Many proteins have multiple PDB entries at different resolutions, with different ligands, or in different conformations. Compare entries before selecting one for downstream use.
• NMR structures: NMR entries do not have a resolution value. They provide an ensemble of conformations rather than a single structure. Assess quality by ensemble RMSD and Ramachandran statistics.

Missing ligands in downloaded structures

• Apo vs. holo structures: Not all structures contain bound ligands. "Apo" structures have the protein alone, while "holo" structures include ligands. Include the ligand name in your search to find co-crystal structures.
• HETATM records: Ligands are stored as HETATM records in PDB files. Some processing tools strip HETATM records. Check that your downstream tool reads both ATOM and HETATM lines.
• Crystallization artifacts: Some HETATM entries are crystallization additives (glycerol, sulfate, phosphate) rather than biologically relevant ligands. Check the ligand identity before assuming it is a drug-like molecule.

Structure file parsing issues

• Chain selection: Multi-chain structures may contain biological assemblies, crystal symmetry mates, or multiple copies in the asymmetric unit. Select the appropriate chain(s) for your analysis.
• Alternate conformations: Some residues have multiple conformations (altloc indicators A, B, C). Downstream tools may need a single conformation. Most tools default to the A conformation.
• Modified residues: Non-standard amino acids (selenomethionine, phosphoserine) may not be recognized by all tools. Convert to standard residues if needed.

Timeout errors

• RCSB APIs are generally reliable but may experience load during peak hours.
• Complex text queries matching thousands of structures take longer to return. Add more specific terms to narrow results.
• The metadata enrichment step fetches details for each of the top 10 results sequentially. If one entry is slow, the overall response is delayed.

Still stuck?

When reporting an issue, include:

• The exact search query or PDB ID used
• Whether the issue is with search or download
• The file format requested (PDB or CIF)
• The error message or unexpected behavior
• What downstream tool you are trying to feed the structure into

Read next