---
title: PDB Search troubleshooting
description: Fix empty PDB searches, invalid or obsolete 4-character IDs, missing HETATM ligands in apo structures, altloc conformations, and RCSB timeouts.
tags:
  - pdb
  - troubleshooting
---

When [PDB Search](/docs/pdb) 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