AutoDock Vina Errors and How to Fix Them: The 10 That Stop Beginners

Almost every AutoDock Vina error is an input problem, not a docking problem. A message starting “PDBQT parsing error” means the ligand or receptor file was built wrong. One starting “ERROR:” with the help text means a missing argument. A grid box message means your center or size numbers are off. Rebuild the inputs before editing anything by hand.

The first docking run a student attempts rarely produces a score. It produces a wall of text, and the text does not look like anything in the tutorial they were following. The good news is that Vina’s failures are unusually honest: the program names the file, echoes the offending line, and tells you which of three things went wrong. This guide covers the ten failures we see most often in student projects, using the exact message text from the AutoDock Vina 1.2 source, plus the two silent failures that produce numbers without producing an error. Written by the StemSkills Lab team, from 10+ years in sequence and structural bioinformatics, drug discovery and design, and multiscale molecular modeling.

What do AutoDock Vina error messages actually tell you?

Vina reports failures in three families, and knowing which family you are in cuts the search space immediately.

• PDBQT parsing errors. Thrown while reading a structure file. They are printed with the prefix PDBQT parsing error: followed by the reason, and where the parser can identify the guilty line it prints that line below, after a > marker. These always mean the file is malformed, never that the docking is impossible.
• Usage and command line errors. Printed together with the option summary, prefixed ERROR:. Something you typed is missing, duplicated or contradictory.
• Runtime errors. Raised after the inputs load, when the grid box or the affinity maps do not work with the molecules you supplied.

Message wording changed between Vina 1.1.2 and the 1.2 series, so check your version with vina --version before you paste an error into a search engine. Everything quoted below is from the 1.2 branch of the official AutoDock Vina repository; the current release at the time of writing is v1.2.7, published in February 2025. If Vina is entirely new to you, start with our AutoDock Vina tutorial for beginners and come back here when something breaks.

Which AutoDock Vina error do you have?

Find your symptom in the left column, then read the section below for the full fix.

Why does Vina throw a PDBQT parsing error on my ligand?

Because PDBQT is not PDB. It carries AutoDock atom types, partial charges and a torsion tree, and a file missing any of those is not a ligand as far as Vina is concerned. Four messages cover nearly all of these failures.

“Atom type … is not a valid AutoDock type”

The full text is Atom type CL is not a valid AutoDock type (atom types are case-sensitive). and the parser echoes the line it choked on. AutoDock types live in the last column of a PDBQT record and their capitalisation is fixed: chlorine is Cl, not CL or cl. Converters that write PDB-style upper-case element names produce exactly this. A plain PDB renamed to .pdbqt produces it too, because the type column is simply not there.

“Missing TORSDOF keyword”

TORSDOF is the record that tells Vina how many rotatable bonds the ligand has, and the ROOT, BRANCH and ENDBRANCH records around it define the torsion tree. A file without them cannot be flexibly docked. This shows up when someone converts a molecule with a general-purpose tool that has no concept of a torsion tree, or edits a working file and deletes the block by accident.

“No atoms in this ligand” and “This line is too short”

The first means the parser reached the end without reading a single atom, so check the file is not empty and the conversion actually ran. The second means a coordinate line has fewer characters than the fixed-column format requires, which is what happens when a PDBQT is opened in a word processor and saved with wrapped lines, or when a download was cut off.

The fix: build the ligand from a connectivity-aware format

The official AutoDock Vina basic docking tutorial is explicit about the starting point, advising against PDB format for small molecules “since it does not contain information about bond connections”. Start from SDF or MOL2 and use Meeko:

mk_prepare_ligand.py -i ligand.sdf -o ligand.pdbqt

If your ligand has no hydrogens yet, protonate it first. If you are pulling structures from public databases, our guides on converting molecular file formats with Open Babel and preparing a protein and ligand for docking cover the steps either side of this command.

Why does Vina reject my receptor file?

The receptor messages are the mirror image of the ligand ones: Unknown or inappropriate tag found in rigid receptor. and Unexpected multi-MODEL tag found in rigid receptor. The first means a record the parser does not accept survived into the file. The second means the file contains several models, which is normal in an NMR entry and unusable as a rigid receptor. Split the models and keep one.

Prepare the receptor properly rather than deleting lines until the error stops:

mk_prepare_receptor.py -i receptor_H.pdb -o receptor -p -v \
  --box_size 20 20 20 --box_center 15.190 53.903 16.917

The -v option with the box arguments also writes a config text file and a box PDB you can load in PyMOL, which removes an entire class of grid box mistakes later. Note the prerequisite: the input coordinates must already contain hydrogen atoms. Deciding which hydrogens to add is a real scientific choice, not a formality, and our guide to protonation states and adding hydrogens covers how to make it defensibly. Missing loops are the other silent receptor problem, handled the same way as in our common GROMACS errors guide.

Why does Vina say a file is missing when it is right there?

Three separate causes, all of them about paths rather than chemistry.

The config file that is not called what you think. The AutoDock Vina FAQ answers this one directly: file browsers hide extensions, so a file you believe is conf.txt is often conf.txt.txt. Turn extensions on in Windows File Explorer, then confirm with dir on Windows or ls on Linux and macOS that the name and the folder both match what you typed.

Arguments that never arrived. ERROR: The receptor or affinity maps must be specified. and ERROR: Missing ligand(s). are printed along with the full option list. If you are passing a config file, one misspelled key inside it is enough: Vina reads receptor, not reciever or protein. Print the file and read it character by character.

Vina itself not on the PATH. A shell reporting vina: command not found, or Windows reporting that vina is not recognised as an internal or external command, is not a Vina error at all. The binary is not where your shell is looking. Either call it by full path or add its folder to the PATH, as covered in our walkthrough on installing AutoDock Vina on Windows.

What is wrong with my grid box?

The grid box causes more wasted student weeks than the parser does, because two of its three failure modes still produce numbers.

“Grid box dimensions must be greater than 0 Angstrom”

Vina checks that size_x, size_y and size_z are all positive before it builds the maps. A zero usually means the value was never read: a typo in the key name, a stray space, or a config file that Vina opened but that contains something other than what you expect.

The 27000 ų warning, and why it matters

When the box volume exceeds 27000 ų, Vina prints WARNING: Search space volume is greater than 27000 Angstrom^3 (See FAQ). This is the single most common beginner mistake, and the FAQ names the cause: users specify the search space in grid points of 0.375 Å, as in AutoDock 4, when Vina expects Ångströms. The arithmetic is worth doing once. A 40 point box in AutoDockTools spans 40 × 0.375 = 15 Å. Type 40 into a Vina config and you have asked for a 40 Å box, which is 64000 ų, roughly nineteen times the volume you intended.

The docs recommend keeping the box as small as it can be while still enclosing the site, and avoiding boxes larger than 30 × 30 × 30 Å unless you also raise exhaustiveness. Our dedicated guide on setting the grid box center and size walks through deriving both from a co-crystallised ligand, and finding the binding site covers what to do when there is no bound ligand to copy.

“The ligand is outside the grid box”

The full message tells you the remedy: increase the size of the grid box or center it accordingly around the ligand. In practice the center coordinates were taken from a different structure, a different chain, or a superimposed copy that was never saved. Load the receptor and the box PDB together in PyMOL and look before you run again.

Why are my binding affinities identical, absurd or different every run?

These produce no error at all, which makes them more dangerous than the ones that do.

Different results on every run. This is expected. The search is stochastic, and the FAQ is precise about the remedy: “Exact reproducibility can be assured by supplying the same random seed to both calculations, but only if all other inputs and parameters are the same as well.” Record your --seed in your methods. Our guide to exhaustiveness and reproducible docking covers how many repeats a claim actually needs.

One pose, or scores clustered around -2 to -4 kcal/mol. Usually the box is centred on solvent rather than the pocket, or the input ligand is a flat 2D structure. The FAQ lists a 2D ligand explicitly among the reasons a docking fails to find the right pose. Generate 3D coordinates before you convert.

Poses that look right except for the hydrogens. Not a bug. Vina uses a united-atom scoring function that evaluates only heavy atoms, so hydrogen positions in the output are arbitrary. The hydrogens in the input still matter, because they decide which atoms are donors and acceptors.

A single pose that will not improve. The default exhaustiveness is 8. The official tutorial raises it to 32 for imatinib against Abl kinase and notes that at 32 Vina most often returns one docked pose, while the default sometimes returns several end-to-end flipped poses with worse energies. Raising exhaustiveness costs time, not accuracy. Interpreting what comes back is a separate skill, covered in how to interpret molecular docking results.

Do wrong Gasteiger charges break a Vina docking?

With the default Vina force field, no. The FAQ states plainly that “AutoDock Vina ignores the user-supplied partial charges”, handling electrostatics through its hydrophobic and hydrogen bonding terms instead. The charges in your PDBQT are along for the ride.

Two conditions change that answer. Protonation still matters, because the hydrogens present at preparation time determine donor and acceptor assignment. And if you run with --scoring ad4, you are using the AutoDock4 force field with precomputed electrostatic maps from autogrid4, where charges do contribute. Check which force field you are running before you spend an afternoon on charge assignment.

This distinction traces back to how the two programs differ. Trott and Olson reported that AutoDock Vina “achieves an approximately two orders of magnitude speed-up compared with the molecular docking software previously developed in our lab (AutoDock 4), while also significantly improving the accuracy of the binding mode predictions” (Trott and Olson, Journal of Computational Chemistry 31:455-461, 2010). The 1.2 series then brought the AutoDock4 scoring function, macrocycles, multiple-ligand docking, batch mode and Python bindings back into Vina (Eberhardt, Santos-Martins, Tillack and Forli, Journal of Chemical Information and Modeling 61:3891-3898, 2021). Two scoring functions in one binary is why the charge question has two answers.

How do you stop these errors happening at all?

Six checks, in the order that catches the most failures earliest.

1. Run vina --version and write it in your notes. Error text and default behaviour differ across versions.
2. Build the ligand from SDF or MOL2 with Meeko, never from a PDB, and never by renaming a file.
3. Add hydrogens to the receptor before preparing it, and decide the protonation states deliberately.
4. Generate the box config with mk_prepare_receptor.py -v so the center and size come from one source instead of being retyped.
5. Load the box PDB with the receptor in PyMOL and confirm the box encloses the pocket before you dock.
6. Set --seed and --exhaustiveness explicitly on every production run, and record both.

Docking is one stage in a longer workflow. If you are planning where it sits in your training, our molecular docking pillar guide covers the full sequence, and the computational biology skills roadmap shows what to learn before and after it.

Frequently asked questions

Can I fix a PDBQT parsing error by editing the file in a text editor?

Occasionally, for a single wrong atom type. Usually not, because the underlying problem is a missing torsion tree or missing typing that no hand edit can supply correctly. Rebuilding from SDF with Meeko takes seconds and is reproducible in your methods section.

What is the difference between a PDB and a PDBQT file?

PDBQT adds AutoDock atom types, partial charges (the Q and T in the name) and, for ligands, a torsion tree defined by ROOT, BRANCH and TORSDOF records. Vina cannot dock a plain PDB, and renaming the extension does not convert it.

Why does Vina give a different score every time I run it?

The search algorithm is non-deterministic and starts from random conformations. Passing the same --seed with identical inputs and parameters reproduces a run exactly. Report the seed and the exhaustiveness with your results.

Should I ignore the 27000 ų search space warning?

Only if you meant to use a box that large, which is rare for a defined pocket. Check first whether you typed AutoDock 4 grid points instead of Ångströms. If the large box is intentional, raise exhaustiveness to compensate, and expect longer run times.

Does AutoDock Vina run on Windows?

Yes, and the official basic docking tutorial is written for macOS, Linux and the Windows Subsystem for Linux. Most Windows-specific problems reported by students are hidden file extensions and PATH configuration rather than anything in Vina itself.