---
title: Troubleshooting BLAST
description: '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.'
tags:
  - blast
  - troubleshooting
---

When a [BLAST](/docs/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](/docs/blast/databases), [search options](/docs/blast/options), and the [remote guide](/docs/blast/remote).

## 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](/docs/blast/options) and [databases](/docs/blast/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