Troubleshooting BLAST
Fix a missing .nin or .pin index, an out-of-memory run, NCBI 429 throttling on -remote, and an empty hit list — plus when to re-run and when to stop.
When a BLAST job errors out, stalls, or returns nothing, this page covers the common failure modes — from missing database index files and out-of-memory conditions to NCBI remote throttling, version mismatches, and empty hit lists — plus a logging checklist and when to re-run versus stop and fix. For how to build databases and set search options correctly in the first place, see local database prep, search options, and the remote guide.
Common issues
BLAST Database error: No alias or index file found Confirm makeblastdb
ran successfully and the -db path points to the directory containing
.nin/.nhr/.nsq (nucl) or .pin/.phr/.psq (prot) files. Verify permissions
where BLAST runs.
Out-of-memory or tmp storage full Reduce -num_threads, limit
-max_target_seqs, and write outputs to outputs/ on the attached volume
instead of /tmp.
Remote BLAST throttling For NCBI remote runs (-remote), respect NCBI rate
limits and batch queries. If you see HTTP 429s, add sleeps between submissions
and use smaller query files.
Mismatched versions Pin BLAST+ version and rebuild databases with the same version used in queries to avoid index incompatibilities.
No hits returned A truly empty result is not always an error. First confirm the query and database types match your program (a protein query needs a protein database, or blastx/tblastn to bridge nucleotide↔protein). Then loosen the search: raise the -evalue cutoff, remove restrictive -taxids filtering, or search a broader database. See search options and databases.
Program/database type mismatch blastn searches nucleotide↔nucleotide and blastp protein↔protein; using the wrong pair either errors or silently returns nothing. Match the program to your query and target sequence types.
Logging checklist
- Echo the full command used for each run.
- Capture stdout/stderr to
outputs/run.log. - Store database checksums alongside results.
- Keep a sample of the query FASTA for debugging.
When to re-run vs. stop
- Re-run: transient network failures, HTTP 429/503 from remote API, or interrupted jobs.
- Stop and fix: missing database files, invalid FASTA headers, program/database type mismatch, or disk-full errors.
Read next
Was this page helpful?
Remote BLAST guide
Run BLAST against NCBI's hosted databases with the -remote flag instead of shipping and indexing data yourself.
Docking & MD overview
Locate the pocket, generate candidate poses for a small molecule, then rescore them by binding free energy — run as much of the arc as your question needs.