Troubleshooting ChEMBL

This page helps you diagnose the common failure modes of a ChEMBL search — rate limits and throttling, compounds that return zero results, InChIKey mismatches across databases, large-query timeouts, and how to interpret bioactivity values that seem inconsistent between studies.

Troubleshooting ChEMBL

This guide covers the most common issues encountered when searching ChEMBL on the platform, along with solutions and workarounds.

API rate limits and throttling

Symptom: Searches return 429 errors or results appear incomplete.

The ChEMBL REST API at EMBL-EBI enforces rate limits to protect shared infrastructure. The platform batches requests internally, but very broad queries can still trigger throttling.

• Narrow your search: Add an activity type, raise the potency or pChEMBL threshold, or ask for fewer results. Searching for "all IC50 data" without a target will attempt to retrieve millions of records.
• Retry after a pause: Rate limits reset after a short cooldown (typically 30-60 seconds). The platform retries automatically with exponential backoff, but persistent 429s indicate the query scope is too large.
• Use specific ChEMBL IDs: Queries by ChEMBL target ID (e.g., CHEMBL203) are faster and less likely to be throttled than free-text gene name searches.

Compound not found

Symptom: A compound you expect to find returns zero results.

• Check the identifier format: ChEMBL compound IDs start with CHEMBL followed by a number (e.g., CHEMBL25 for aspirin). Do not confuse these with PubChem CIDs or DrugBank IDs.
• Try alternative identifiers: Search by SMILES, InChIKey, or common name instead of ChEMBL ID. Not all compounds have been assigned ChEMBL IDs.
• Verify the compound exists in ChEMBL: ChEMBL only contains compounds from curated literature. Newly synthesized or proprietary compounds will not appear. Check chembl.gitbook.io for the latest release notes.
• Canonicalize SMILES: Non-canonical SMILES may fail exact-match lookups. Use RDKit canonicalization before searching.

InChIKey mismatches

Symptom: The same compound returns different InChIKeys across databases.

InChIKey differences between ChEMBL and PubChem usually stem from stereochemistry or salt/ion handling:

• Stereochemistry layer: The first 14 characters of an InChIKey encode the connectivity layer. If these match but the second block differs, the compounds share the same scaffold but differ in stereochemistry.
• Salt stripping: ChEMBL stores parent compounds (free base/acid), while some databases index salts. Compare the first block of the InChIKey to check connectivity equivalence.
• Tautomers: Different tautomeric forms generate different InChIKeys. ChEMBL normalizes tautomers during curation, but upstream sources may not.

To resolve mismatches, compare the first 14-character block (connectivity layer) rather than the full 27-character InChIKey.

Large query timeouts

Symptom: Searches hang or time out after 30+ seconds.

• Reduce result scope: Ask for a potency cutoff (e.g., IC50 < 1000 nM) to limit results. Unfiltered bioactivity queries for popular targets like EGFR can return 50,000+ records.
• Raise the pChEMBL floor: Asking for a minimum pChEMBL (e.g., ≥ 6, equivalent to 1 µM) excludes weak-potency records and narrows the result set.
• Ask for fewer results: A bioactivity search returns at most 100 records per search (25 by default) — asking for fewer returns faster.
• Target-first workflow: Run a target search first to confirm the ChEMBL target ID, then use that ID for a focused bioactivity search. This avoids the slower free-text resolution step.

Bioactivity data interpretation

Symptom: Activity values seem inconsistent or hard to compare across compounds.

Comparing across studies

Activity values from different assays are not directly comparable. Key factors:

Best practices for comparison

• Filter by a single activity type (e.g., only IC50) when ranking compounds
• Use confidence ≥ 7 to ensure target assignment is reliable
• Check the assay description for context on experimental conditions
• For published SAR, look for compounds tested in the same assay (same assay ChEMBL ID)

Activity value ranges

Missing or incomplete data

Symptom: Expected fields (e.g., SMILES, molecular weight) are null.

• Confidential structures: Some ChEMBL entries from journal publications have redacted structures. The bioactivity data exists but the compound structure is marked confidential.
• Peptides and biologics: Large molecules (peptides, antibodies) may lack SMILES representations. Check for InChI or sequence-based identifiers instead.
• Assay-level gaps: Not all assays report all fields. pchembl_value and standard_units may be null for older entries.

When to retry vs. adjust

• Retry: Transient 429/500 errors, network timeouts, or intermittent API unavailability.
• Adjust query: Zero results with valid identifiers, consistent timeouts on broad queries, or unexpected data volumes.
• Switch tools: If you need computed properties (logP, TPSA) rather than measured bioactivity, use PubChem. If you need regulatory approval data, use DrugCentral.

Getting help

If issues persist:

1. Check the ChEMBL FAQ for known data issues
2. Verify the ChEMBL API status at www.ebi.ac.uk/chembl/api/status
3. Review the ChEMBL Web Services documentation for query syntax details

Read next