Why Some Ligands Fail Before AutoDock Vina: A Practical SDF Preflight Checklist

An .sdf filename is a container and format declaration, not proof that a molecule is ready for docking. Meeko's current ligand-preparation documentation expects an RDKit molecule with explicit hydrogen atoms and 3D coordinates; Meeko then assigns docking parameters and produces the PDBQT consumed by AutoDock Vina [1,2]. It does not silently invent the missing hydrogens or coordinates [2].

That boundary explains a frustrating class of failures: a structure can look acceptable in a viewer, yet stop before Vina ever starts. The practical question is therefore not merely Can this file be converted? It is Can every chemical decision between the source record and the docking input be inspected and defended?

The path from SDF to a Vina result contains several separate transformations:

source SDF record → parsed molecule → sanitized chemical graph → selected docking state → usable 3D geometry → parameterized PDBQT → AutoDock Vina search.

Only the final step is docking. If a workflow collapses all earlier failures into a generic "conversion error," the researcher cannot tell whether the problem is a malformed record, an impossible valence, an unresolved salt, an unspecified stereocenter, a geometry problem, or a prepared-file mismatch.

An SDF can contain one molecule or many [1]. Before chemistry is evaluated, confirm that the intended record can be read and assigned a stable identity. Truncated blocks, inconsistent atom or bond counts, broken delimiters, and empty records belong to this gate. They should not be disguised as chemistry failures.

For a batch, preserve the source filename, record position, molecular title or external identifier, and a checksum. If a parser returns no molecule, record that terminal state explicitly. Silent omission changes the denominator: a report of 94 completed ligands means something different if six other submitted records disappeared without explanation.

RDKit sanitization generates chemical properties such as ring membership and hybridization while checking whether a molecule can be represented by a reasonable Lewis structure [3]. Its default valence checks reject atoms whose specified bond orders and hydrogen count exceed the allowed valence [3]. RDKit can also report specific problems such as an AtomValenceException or KekulizeException [4].

Those messages are diagnostic, not instructions to delete a bond or neutralize an atom until the error disappears. First compare the record with the authoritative source. A wrong formal charge, bond order, aromatic flag, or hydrogen placement may be a transcription problem. Unusual but intentional chemistry may instead require a documented specialist workflow.

A chemically parseable record can still leave decisions that matter to docking. A salt or solvent fragment must not be removed merely because it is smaller. An undefined stereocenter must not become an arbitrary isomer. A protonation or tautomer state must match a stated policy and intended environment.

Hydrogen handling is particularly easy to underestimate. Vina uses a united-atom scoring function, but its documentation states that input hydrogens determine hydrogen-bond donor and acceptor assignments [6]. The basic Vina tutorial also advises checking protonation and warns against using PDB as the source format for small-molecule preparation because it does not carry bond connectivity [5].

Finally, Meeko expects explicit hydrogens and 3D positions [1,2]. If coordinates are absent, flat, or implausible, generate and inspect a conformer under a declared method. If minimization reaches a limit or the chemistry is unsupported by the chosen force field, preserve the warning rather than promoting the ligand silently.

Meeko uses the sanitized RDKit molecule to assign AutoDock atom types, partial charges, and rotatable bonds before writing PDBQT [2]. A successful write is necessary, but it is not the final integrity check. Connect the prepared artifact to the exact source record and preparation report, then verify basic invariants such as identity, expected heavy atoms, formal-charge consistency, finite coordinates, and a nonempty rotatable-bond model.

If that comparison fails, exclude the artifact from the current run and preserve the reason. Regenerating files until one happens to pass removes the evidence needed to understand which chemical assumption changed.

MolNexus uses three current preflight states to keep eligibility separate from file creation. These labels are specific to the MolNexus workflow; they are not an AutoDock Vina or Meeko standard.

The inputs came from the original YuelDesign dataset deposited on Zenodo; its cdk2_yueldesign.tar archive contains the molecules generated for CDK2 [8]. The eight inputs were selected before their preparation outcomes were known. The receptor was the 1.34 Å X-ray structure of apo human CDK2, PDB 4EK3 [9], and the retained workflow used AutoDock Vina 1.2.7 [10].

The full selection rule, preparation outcomes, docking settings, scores, and evidence boundary remain available in the documented AI-generated ligand workflow. Here, the narrower purpose is to show what a useful preflight report reveals before compute begins.

Use this checklist before a full ligand library is launched, then keep the preparation report beside the docking record. The broader guide to preparing proteins and ligands for AutoDock Vina covers the end-to-end setup. Before scaling, the separate workflow validation guide explains how to test pose recovery, screening discrimination, and robustness.

MolNexus 0.1.0 brings ligand preflight, receptor preparation, interaction-box definition, AutoDock Vina 1.2.7 execution, pose review, exports, and local job history into one Windows desktop workflow. For ligand preparation, it keeps the source and diagnostics visible, classifies each input as Ready, Review, or Excluded, and sends only Ready inputs to docking. Suggested resolutions are not applied automatically.

That design does not remove scientific judgment. It places the judgment at a visible gate, before a warning becomes an invisible transformation and before a batch consumes compute time.

The fastest docking run is the one that never starts with an ambiguous ligand. A preflight gate turns preparation from a hidden conversion step into a reviewable scientific record: every source remains identifiable, every warning has an owner, every exclusion stays in the denominator, and only eligible inputs consume docking time.

Use the checklist on a representative subset before scaling the library. If the same failure class repeats, improve the source or protocol once and document it, rather than patching molecules one by one without a reproducible rule.