How to Fix 'BAM File Not Indexed' Errors in IGV and UCSC

By Dr. Zubair Khalid, DVM, MS, PhD · 2026-11-10

The most likely cause of a "BAM file not indexed" error is simple: the .bai index file is missing, or it no longer matches the BAM it sits beside. The first thing to check is whether an index exists in the same directory or at the same URL path as the BAM, and whether that index is newer than the BAM file itself. If either answer is no, you have found the fault in under a minute.

Almost every remaining case traces back to one of four conditions. The BAM was never coordinate sorted. The index is stale because the BAM was rewritten after indexing. The index exists but sits at a path or under a name the browser does not look for. Or the file is not actually a BAM at all, even though it carries a .bam extension.

This guide works from the most common cause to the rarest. It gives you the exact commands to confirm each failure, the fix for IGV and for UCSC, and a diagnostic order you can reuse the next time a browser refuses to draw coverage. Every fix here preserves the original data. Nothing in this workflow requires you to re-sequence a sample.

The reason the error is so common is structural. BAM files are compressed, and a compressed stream cannot be jumped into at an arbitrary point without help. Genome browsers do exactly that kind of jumping all day. The index is what makes the jumping possible.

What a BAM Index Actually Does

BAM is a binary, block-compressed representation of SAM, the text format that stores aligned reads. Each alignment record carries a read name, a flag, a reference sequence name, a leftmost position, a mapping quality, a CIGAR string describing how the read aligns, and the read sequence with its quality scores. In a BAM, those records are grouped into compressed blocks so that the file stays small enough to move and store.

That compression creates a problem for interactive viewing. To draw a 200-kilobase window in the middle of a 60-gigabyte BAM, a viewer must find the compressed block that holds the first read overlapping that window. It cannot scan from byte zero to byte sixty billion every time you drag the viewport. The BAM index solves this by storing a mapping from genomic region to virtual file offset, which is a pair of numbers pointing at a compressed block and an offset inside the decompressed block. Accessing raw sequencing data from BAM files is a necessary and time-consuming step in nearly all sequence analysis tools, and parallel access libraries exist specifically to make that step faster [1].

The index format most people mean is BAI, the binary alignment index produced by samtools index. A newer variant, CSI, is the coordinate-sorted index that handles reference sequences longer than the BAI limit. Most BAM I/O libraries and most genome browsers accept BAI. The details of block parsing matter for performance, and libraries such as RabbitBAM report 2.1 to 3.3 fold speedups over standard HTSlib parsing on next-generation sequencing data by attacking exactly this layer [2]. None of that changes the contract the browser expects: a BAM, a matching index, and a coordinate-sorted header.

The Three-Part Contract

Every viewer checks three things before it draws a read.

1. Sort order. The BAM header must declare coordinate sorting, normally @HD VN:1.6 SO:coordinate. A name-sorted or unsorted BAM cannot be indexed in a way that supports regional queries.
2. Index presence and freshness. A .bai (or .csi) must exist and must have been built from the current contents of the BAM.
3. Reference agreement. The @SQ lines in the BAM header must describe contigs that exist in the genome the browser has loaded.

When any one of these fails, the browser reports a loading error. The error text varies, but the underlying fault is one of those three. That is why the diagnostic sequence below is short.

How to Fix the BAM File Not Indexed Error in IGV and UCSC: A 60-Second Diagnostic Sequence

Run these checks in order. Stop at the first failure.

1. List the files. ls -lh sample.bam sample.bam.bai sample.bai shows what exists and when each file was written.
2. Compare timestamps. If the .bai is older than the .bam, the index is stale. Re-index before doing anything else.
3. Check sort order. samtools view -H sample.bam | head -n 5 and look for SO:coordinate in the @HD line.
4. Check file integrity. samtools quickcheck -v sample.bam prints a complaint and returns nonzero if the file is truncated or missing its end-of-file marker.
5. Confirm the file is really BAM. file sample.bam should report BGZF compressed data, not gzip, not CRAM, not ASCII text.
6. Confirm the index reads. samtools idxstats sample.bam prints one line per contig with mapped and unmapped counts. If this command fails, the index is broken.
7. Compare contig names. Put the @SQ names from the header side by side with the contig names in the browser's loaded genome.
8. For remote files, test range requests with curl -r 0-99 -o /dev/null -w "%{http_code}\n" https://host/sample.bam. A server that honors byte ranges returns 206.

Each of those eight checks maps to a specific cause in the table below.

Troubleshooting Table

Cause 1: The Index Is Missing

This is the dominant cause. A BAM can be perfectly valid, coordinate sorted, and complete, and still fail to load because nobody ran the indexing step.

Create the index with samtools:

samtools index -@ 8 sample.bam

The -@ 8 flag uses eight additional threads for compression and decompression. On a laptop, use -@ 4. The command writes sample.bam.bai beside the BAM. Verify it with:

samtools idxstats sample.bam

You should see one row per reference sequence with three columns: contig name, mapped read count, unmapped read count. A failure here means the index is corrupt or was built against a different BAM.

Alternatives exist if samtools is not installed. Sambamba builds indexes quickly with sambamba index -t 8 sample.bam. Picard does the same with picard BuildBamIndex I=sample.bam O=sample.bam.bai. All three produce a BAI that IGV and UCSC accept.

If your reference contains sequences longer than roughly 512 megabases, the classic BAI format cannot address them. Build a CSI index instead:

samtools index -c sample.bam

That writes sample.bam.csi. Confirm that your viewer version supports CSI before you standardize on it. When in doubt, keep both indexes side by side. The BAI handles the contigs it can address, and the CSI covers the rest.

One operational note. Indexing is fast compared with alignment, but it is not free on a 100-gigabyte BAM. Run it once as the final step of your pipeline, not every time you open a browser session.

Cause 2: The BAM Was Never Coordinate Sorted

A BAI index is only meaningful on a coordinate-sorted file. If the aligner emitted reads in the order they appeared in the FASTQ, or if a downstream tool re-sorted by read name for duplicate marking and nobody re-sorted by coordinate afterward, the header will say SO:queryname or SO:unsorted.

Confirm with:

samtools view -H sample.bam | grep '^@HD'

The fix is a sort followed by an index:

samtools sort -@ 8 -m 2G -o sample.sorted.bam sample.bam
samtools index -@ 8 sample.sorted.bam

The -m 2G flag caps memory per thread at 2 gigabytes, which keeps a desktop workstation from swapping. On a server with more RAM, raise it.

Sorting rewrites the file, so any existing index is now invalid. Delete or overwrite it. Never copy a .bai from the unsorted file onto the sorted one. The index stores virtual offsets that refer to specific byte positions, and those positions change completely after a sort.

A subtle variant of this cause appears when someone sorts with a tool that writes a new BAM but preserves the old header verbatim. The header still claims SO:coordinate from an earlier step while the records are in a different order. samtools quickcheck will pass. samtools idxstats may even pass. Coverage in the browser will be wrong in a way that looks like a data problem rather than an index problem. The reliable check is to sort with a tool that rewrites the header, then index that output.

Cause 3: The Index Is Stale or Truncated

BAM files get rewritten more often than people expect. A pipeline rerun, a reheader operation, a merge that overwrites the output path, or a filtering step that writes to the same filename all invalidate the index. The .bai remains on disk, so the browser finds an index, opens it, and gets nonsense.

The tell is the filesystem timestamp. If sample.bam is newer than sample.bam.bai, rebuild the index. Do not trust a timestamp alone if files were copied with cp -p, which preserves the original modification time and can make a stale pair look consistent. In that case compare content hashes recorded at build time, or simply re-index.

Truncation is the second variant. A copy interrupted by a dropped connection, a full disk, or a killed process leaves a BAM that ends mid-block. The BAM specification includes a specific end-of-file marker in the final compressed block. samtools quickcheck -v sample.bam detects its absence and reports the file as truncated. Re-transfer the file, then verify with a checksum such as md5sum or sha256sum against the value recorded at the source.

samtools quickcheck -v sample.bam

No output and a zero exit status means the file passed. Any output means do not index it. Indexing a truncated BAM produces a truncated index, and the browser failure will look identical to the original problem.

Safety Note on Destructive Commands

Sorting, filtering, and re-indexing all write new files. Keep the original BAM untouched until the new file passes samtools quickcheck and samtools idxstats. Before running rm on an old index or an intermediate BAM, list the files you intend to delete and confirm the paths. A mistyped wildcard in a directory of 40 BAMs is not recoverable without the original data.

Cause 4: The Index Exists but Is in the Wrong Place or Under the Wrong Name

IGV and UCSC both guess index locations, and both guesses follow conventions that are easy to break.

IGV looks for an index next to the BAM, under common names. The two you will see in the wild are sample.bam.bai and sample.bai. Both are valid. If your indexing tool wrote one form and your collaborator's tool wrote the other, and someone renamed files during a transfer, the browser may look for a name that is not there. The fix is trivial. Copy or rename the index so both names exist:

cp sample.bam.bai sample.bai

For remote BAMs loaded by URL, the index must be reachable at a URL the viewer can derive, or you must state it. In IGV, use the Load from URL dialog and supply the index URL explicitly when the naming convention does not hold. In UCSC, the custom track line carries the answer. A minimal BAM track looks like this:

track type=bam name="sample" bigDataUrl=https://host/data/sample.bam bamIndexUrl=https://host/data/sample.bam.bai

For a track hub, the equivalent lives in trackDb.txt:

track sampleBam
type bam
bigDataUrl https://host/data/sample.bam
bamIndexUrl https://host/data/sample.bam.bai
shortLabel Sample
longLabel Sample aligned reads

Declaring bamIndexUrl explicitly removes all guesswork. If you omit it, the browser derives an index path from the BAM URL, and any deviation from that pattern produces exactly the error you are trying to fix.

A related trap is the directory question. If the BAM sits at https://host/project/bam/sample.bam and the index sits at https://host/project/index/sample.bam.bai, nothing will find it. Put the index in the same directory as the BAM unless you are prepared to declare its location in every track and every browser session.

Cause 5: The File Is Not Actually a BAM

Extensions are not evidence. A file can be named .bam and contain a SAM text file, a CRAM file, a plain gzip stream, a partial download, or an HTML login page served by a misconfigured portal.

Check with:

file sample.bam
samtools view -H sample.bam | head

A genuine BAM reports as BGZF compressed data and yields a SAM header. A SAM text file starts with @HD in plain text. A CRAM file reports as CRAM and needs a .crai index plus a reference FASTA to decode. A plain gzip stream from a .gz FASTQ renamed to .bam will fail immediately because it is not block compressed in the BGZF structure that BAM requires.

Converting a SAM to BAM is a one-liner:

samtools view -b -o sample.bam sample.sam
samtools sort -o sample.sorted.bam sample.bam
samtools index sample.sorted.bam

CRAM is a legitimate compressed alternative to BAM and is compatible with many software packages [3]. If your data is CRAM, do not fight it. Load it as CRAM with its .crai index and the correct reference, or convert it to BAM with samtools view -b -T reference.fa -o sample.bam sample.cram if the viewer in front of you only speaks BAM.

Where BAM Fits Among Bioinformatics File Formats

Sorting out this error is easier once the file formats are clear, because several of them look interchangeable and are not.

FASTQ holds raw sequencing reads. Each record carries a sequence and a per-base quality score, which is what makes FASTQ the input to alignment. FASTA holds sequences without per-base quality scores and is the usual container for a reference genome. The distinction matters here because a reference FASTA must be indexed separately with samtools faidx before many tools will use it, and that .fai index is unrelated to the BAM .bai.

SAM is the text alignment format. BAM is its compressed binary equivalent. CRAM is a reference-based compressed alternative. VCF holds variants. bigWig holds coverage or signal tracks. Clinical workflows routinely move between FASTQ, BAM, and VCF, and the Integrative Genomics Viewer is built to display data in those formats side by side [4]. Reviews of online resources for high-throughput sequencing make the same point about format literacy being a prerequisite for analysis and visualization [5].

BAM is also a container that other fields have adopted. Proteomics pipelines use a protein BAM variant so that peptide spectrum matches can be shown in genome browsers [6]. Long-read pipelines treat aligned BAM as a carrier of alignments and sometimes base modification calls [7]. Downstream tools from polyadenylation analysis to viral insertion detection take a BAM as their starting point [20, 11]. Methylation suites compress BAM into their own representations [8]. Targeted pathogen pipelines can run from any BAM regardless of which enrichment method produced it [9].

The practical consequence is uniform. Whatever generated your BAM, the browser still needs the same three things: coordinate sorting, a matching index, and a reference that agrees with the header.

Cause 6: Reference Genome or Contig Mismatch

A BAM can be sorted and indexed correctly and still fail to display reads if the browser has loaded a genome whose contig names do not match the @SQ lines.

The classic case is chr1 versus 1. Ensembl-style references use 1, 2, X. UCSC-style references use chr1, chr2, chrX. A BAM aligned to one and displayed against the other will load its header, may show a track, and will show nothing where reads should be. Some viewers warn that contigs in the file are absent from the genome. Others fail silently.

Check with:

samtools view -H sample.bam | grep '^@SQ' | head -n 30

Then compare against the chromosome list in the genome selector of your viewer. In IGV, the genome popup shows the loaded assembly, and the loaded assembly's contig set is what matters. In UCSC, the db parameter of the track or the assembly selected in the browser determines it.

The fix is to align against the assembly the browser expects, or to load the assembly the data was aligned to. Liftover is not a substitute. It changes coordinates, and applying it to a BAM requires a dedicated tool and a careful validation step. Renaming contigs in a header with samtools reheader is possible but invalidates the index, so re-index afterward.

A second variant involves alternate contigs and scaffolds. A BAM aligned to a reference with hundreds of unplaced scaffolds will have @SQ entries the browser's genome does not include. Reads on those contigs are simply not shown. That is expected behavior, not an error. If your variant of interest sits on an unplaced scaffold, load a reference that includes it.

Cause 7: The Server Cannot Serve Byte Ranges

Local files fail for local reasons. Remote files add a network layer, and that is where the strangest index errors come from.

A browser loading a remote BAM issues HTTP range requests. It asks the server for specific byte ranges, and it needs the server to answer with status 206 and the requested bytes. A server that ignores the range header and returns the whole file with status 200 will technically deliver data, but the browser's random access model collapses. Static file servers, object storage with signed URLs, and most CDN-backed hosts handle ranges correctly. Application endpoints that stream files through a script frequently do not.

Test it directly:

curl -r 0-99 -o /dev/null -w "%{http_code}\n" https://host/data/sample.bam

A 206 is what you want. A 200 means the range request was ignored. A 403 means authentication failed. A 404 means the path is wrong, which is worth ruling out before you debug anything else.

Authentication is the next layer. Private buckets need signed URLs with an expiry. If the BAM URL works and the index URL does not, the index may sit in a different bucket with different permissions, or the signed URL for the index may have been generated separately and already expired.

Cross-origin access matters for web-based viewers. IGV running as a desktop application is not subject to browser same-origin policy. IGV running in a browser tab is. If the data host does not send permissive CORS headers, the web viewer fails while the desktop viewer succeeds on the same URL. That difference is a useful diagnostic signal.

Cause 8: Paths, Permissions, and Encoding

Local permission problems produce a generic failure that reads like an index problem. If the browser process cannot read the .bai, it reports a missing index.

Check permissions on both files:

ls -l sample.bam sample.bam.bai

The user running IGV needs read access to both. On a shared cluster, a file copied by one user with a restrictive umask will be readable by that user and invisible to everyone else, including the browser running under a different account.

URL encoding is the other common trap. A space in a filename becomes %20 in a URL. A # character truncates the URL at the fragment. An ampersand splits query parameters. Underscores and hyphens are safe, spaces and special characters are not. Rename files to a conservative character set before publishing them, and keep the same name for the index.

Case sensitivity also bites when data moves between filesystems. A file named Sample.BAM.bai will not be found when the browser asks for sample.bam.bai on a Linux server, even though the same pair worked on a case-insensitive desktop.

Cause 9: Index Type Limits on Very Large or Very Fragmented References

The BAI format stores coordinates in a fixed-width scheme that caps the addressable position on a single reference sequence at roughly 512 megabases. Most human chromosomes fit comfortably. Some plant and amphibian assemblies do not. Certain fungal and parasite references with unusually long scaffolds can also exceed it.

The symptom is specific. The index builds without error, samtools idxstats works, and the browser still fails or shows partial data because it cannot resolve positions beyond the limit on the affected contig.

Build a CSI index:

samtools index -c sample.bam

CSI uses a variable-width scheme and handles longer sequences. Check that your viewer version supports CSI before you make it the only index you ship. Keeping both sample.bam.bai and sample.bam.csi in place is a safe default for mixed environments.

A related limit appears with extremely fragmented assemblies containing tens of thousands of short contigs. Index files get larger, load times increase, and some viewers handle the contig list poorly. There is no format fix for this. The practical fix is to load a reference with fewer, longer sequences, or to restrict the view to the contigs that matter.

IGV-Specific Fixes

IGV is a desktop application and a JavaScript library, and the two fail differently. In the desktop application, load the BAM through File > Load from File, or through Load from URL for remote data. If the index naming convention does not hold, specify the index in the load dialog rather than hoping for auto-detection. The clinical use of IGV for variant review depends on getting this loading step right, because the whole point of the tool is visual inspection of aligned reads against a reference [4].

Three IGV behaviors are worth knowing.

First, IGV caches track state. If you replace a BAM and its index while a session is open, reload the track rather than assuming the browser will notice. A stale in-memory view can look exactly like a failed index.

Second, the genome must be loaded before or with the BAM. If the genome is set to a build that does not match the @SQ lines, the track loads and the reads do not appear where you expect.

Third, for web deployments, IGV can consume data through an htsget endpoint, which serves BAM and CRAM over a standardized API and handles indexing on the server side. If your organization runs htsget, the client no longer needs to manage .bai files at all.

UCSC-Specific Fixes

UCSC Genome Browser BAM tracks are declared, not auto-detected. The custom track line or the trackDb.txt entry must name the BAM and, in practice, should name the index.

The minimal custom track:

track type=bam name="sample" bigDataUrl=https://host/data/sample.bam bamIndexUrl=https://host/data/sample.bam.bai

The minimal track hub stanza:

track sampleBam
type bam
bigDataUrl https://host/data/sample.bam
bamIndexUrl https://host/data/sample.bam.bai
shortLabel Sample
longLabel Sample aligned reads

If the browser reports that the BAM is not indexed while IGV loads the same file, the fault is almost always the track line. Either bamIndexUrl is absent and the derived index path does not exist, or the index URL resolves to a location the browser cannot reach. Paste both URLs into a browser tab and confirm they download.

Two more UCSC behaviors matter. The assembly selected in the browser must match the @SQ names in the BAM, and the track must be added to a session that uses that assembly. And UCSC served over HTTPS requires the data URLs to be HTTPS as well, since a secure page cannot load insecure resources. A mixed-protocol track line fails in ways that look like permission errors.

Prevention Practices

The error is cheap to prevent and expensive to debug under deadline. These practices eliminate most recurrences.

1. Make indexing the last step of the alignment pipeline. Append samtools index -@ 8 sample.bam to the script that produces the BAM. Do not leave it as a manual step for the analyst.
2. Sort and index in the same job. Any tool that rewrites a BAM must be followed by a sort and an index before the file is published.
3. Enforce a naming convention. sample.bam and sample.bam.bai, always, in the same directory. Do not mix sample.bai and sample.bam.bai across a project.
4. Record a checksum at build time. Store the sha256sum of the BAM and the index alongside the file. Verify after every transfer.
5. Treat published BAMs as immutable. If a BAM must change, write a new filename rather than overwriting. Overwriting a published file breaks every cached link and every stored index.
6. Ship the index with the BAM. Archive both files in the same tarball. An archive containing a BAM without its index will regenerate this error for the next person.
7. Automate a load test. A script that runs samtools quickcheck and samtools idxstats on every published BAM catches truncation and stale indexes before a collaborator does.
8. State the index URL explicitly in every track line. Relying on derivation works until someone reorganizes a directory.

Safety and Data-Handling Notes

BAM files contain aligned sequence data and can carry identifying information depending on the source. Uploading a clinical BAM to a public browser instance is a disclosure decision, not a technical convenience. Use access-controlled viewers for identifiable data.

For command-line work, keep the original BAM until the re-sorted and re-indexed version passes validation. Then remove intermediates with explicit paths, not wildcards.

Common Mistakes and Limitations

Assuming the index travels with the BAM. It does not. Copying a BAM between systems without its .bai is the single most frequent cause of this error in shared environments.

Indexing before sorting. The index command may succeed and produce a file, but regional queries will return wrong or missing reads. The header is the authority, not the exit status of the indexing command.

Reusing an index after reheadering. samtools reheader changes the header and therefore the file offsets. The index must be rebuilt.

Trusting an extension. A .bam that is really a CRAM, a SAM, or a partial download produces confusing errors. file and samtools quickcheck settle it in seconds.

Pointing the browser at a directory listing. A URL that returns an HTML index page rather than a BAM produces a parse failure that reads like a format error.

Ignoring contig naming until later. Align to the assembly the viewer expects, or load the assembly the data was aligned to. Do not fix a naming mismatch by renaming contigs unless you are prepared to rebuild the index.

Assuming a BAI works for every reference. Very long sequences need CSI. Check the reference, not just the file size.

Loading a BAM without the genome. IGV and UCSC both need a reference context to place reads. A BAM loaded against the wrong genome looks like an indexing failure and is not.

Ignoring server behavior for remote data. A host that does not honor range requests will fail regardless of how correct your index is.

Overwriting a published BAM in place. Every downstream link, cached track, and stored index becomes invalid at once. Write new filenames.

Limitations worth accepting. The BAM index is a lookup structure, not a validation of alignment quality. A BAM can pass every check in this guide and still contain poor alignments, PCR duplicates, or contamination. Indexing confirms that the file can be read efficiently. It says nothing about whether the data are good.

Frequently Asked Questions

Why does IGV say my BAM is not indexed when the .bai exists?

The index is probably stale, in the wrong directory, or under a name IGV does not check. Compare timestamps first, then confirm the index sits beside the BAM. If both look right, rebuild the index from the current BAM.

Can IGV or UCSC create the BAM index for me?

Build the index outside the browser. Use samtools index, sambamba index, or picard BuildBamIndex and then load the result. Server-side htsget endpoints handle indexing for you, but that requires infrastructure your organization must run.

What is the difference between sample.bam.bai and sample.bai?

Both are BAI indexes for the same BAM. The two names come from different tool conventions. Some viewers check one, some check the other, and keeping both copies in the same directory avoids the ambiguity entirely.

Do I need to sort a BAM before indexing it?

Yes. The index maps genomic coordinates to file offsets, and that mapping only makes sense when records are ordered by coordinate. Check the SO field in the @HD header line, then sort with samtools sort and index the output.

Why does my BAM load in IGV but not in UCSC?

The UCSC track line is most likely missing an explicit bamIndexUrl, or the index URL is not reachable over HTTPS. UCSC does not guess as forgivingly as IGV. Paste both URLs into a browser tab to confirm they resolve.

Can I use a CRAM file instead of a BAM in IGV and UCSC?

Sometimes. Both viewers support CRAM in recent versions, but CRAM needs its own .crai index and the correct reference FASTA. If the viewer in front of you only handles BAM, convert with samtools view -b -T reference.fa -o sample.bam sample.cram.

How do I index a BAM whose reference has very long contigs?

Build a CSI index with samtools index -c sample.bam. The classic BAI format cannot address positions beyond roughly 512 megabases on a single sequence. Confirm that your viewer supports CSI, or ship both index types.

How do I check that a BAM index is valid without opening a genome browser?

Run samtools quickcheck -v sample.bam to confirm the BAM is complete, then samtools idxstats sample.bam to confirm the index reads and returns per-contig counts. If both commands succeed, the file is structurally ready for any viewer.

Sources

1. quickBAM: a parallelized BAM file access API for high-throughput sequence analysis informatics.
2. RabbitBAM: Accelerating BAM File Manipulation on Multi-Core Platforms.
3. A benchmark study of compression software for human short-read sequence data.
4. Clinical Variant Interpretation with the Integrative Genomics Viewer (IGV) for Molecular Pathologists.
5. Online resources for genomic analysis using high-throughput sequencing.
6. proBAMsuite, a Bioinformatics Framework for Genome-Based Representation and Analysis of Proteomics Data.
7. LongReadSum: A fast and flexible quality control and signal summarization tool for long-read sequencing data.
8. wgbstools: a computational suite for DNA methylation sequencing data analysis.
9. Castanet: a pipeline for rapid analysis of targeted multi-pathogen genomic data.