This page helps you diagnose the problems that most often surface with DeepChem — SMILES parsing and featurization failures, poor accuracy or high uncertainty, custom-model training convergence, and inconsistent predictions across runs.

Common issues and fixes

DeepChem uses deep learning models for molecular property prediction. Understanding common issues helps you prepare inputs correctly and troubleshoot prediction problems.

SMILES parsing failures

Verify each SMILES string is valid using the real-time validator in .bloom* or an external tool (RDKit, Open Babel)
Check for unmatched parentheses, invalid ring closure numbers, or incorrect element symbols
Remove salt components (everything after the . separator) if the model expects single molecules
Ensure stereochemistry notation is syntactically correct
For CSV uploads, verify the SMILES column header matches exactly (smiles or SMILES)

Featurization errors

"Cannot featurize molecule": Some complex molecules (metallocenes, large macrocycles, organometallics) may fail specific featurizers. Try switching from MolGraphConv to ECFP or RDKitDescriptors
3D featurizer failures: CoulombMatrix and other 3D featurizers require conformer generation, which can fail for molecules with complex ring systems. Use 2D featurizers as fallback
Missing atom types: Molecules containing rare elements (e.g., Se, Te, Si) may lack featurizer coverage. Restrict inputs to common organic elements (C, N, O, S, P, F, Cl, Br, I)

Poor prediction accuracy

Check whether the molecule is within the model's applicability domain; out-of-domain predictions are unreliable
Pre-trained models are most accurate for molecules similar to their training sets; novel scaffolds may have larger errors
For critical decisions, compare predictions from multiple model architectures (MPNN, GCN, AttentiveFP) and use consensus scoring
If predicting a custom endpoint, ensure the training data is sufficient (500+ molecules recommended) and balanced

Training convergence issues (custom models)

Loss not decreasing: Try reducing the learning rate by 10x (e.g., from 0.001 to 0.0001)
Overfitting (training loss low, validation loss high): Increase dropout, reduce model complexity, or add more training data
Underfitting (both losses high): Increase model capacity (hidden_dim, num_layers) or switch to a more expressive architecture
NaN loss values: Usually indicates learning rate too high or numerical instability. Reduce learning rate and check for extreme values in training labels
Early stopping too aggressive: Increase patience parameter to allow more epochs without improvement

High uncertainty on all predictions

Very high uncertainty across all molecules suggests the model lacks confidence in its predictions
Check that the ensemble size (num_ensemble) or MC-dropout samples (dropout_samples) are sufficient (5 and 20 are good defaults)
Models trained on very small datasets may be inherently uncertain; add more training data if possible
If all molecules are outside the applicability domain, the model may not be appropriate for your chemical series

Batch processing errors

If some molecules in a batch fail while others succeed, check the failed SMILES for parsing errors
Very large batches (>10,000 molecules) may cause memory issues; split into smaller batches
Ensure CSV formatting is consistent (no mixed delimiters, no trailing commas, consistent quoting)

Inconsistent predictions across runs

Pre-trained model predictions should be deterministic for the same input
Custom model predictions may vary slightly due to floating-point non-determinism on GPU
For reproducible custom training, set random seeds in the configuration
Ensemble predictions naturally vary between runs unless all ensemble members use fixed seeds

Still stuck?

Provide the job ID, model architecture, endpoint, and featurizer used
Include the SMILES of problematic molecules and any error messages
Note whether the issue is at featurization, prediction, or training stage
For custom models, share the dataset size and label distribution

DeepChem troubleshooting