STAR Has a Bug?! A Complete Debugging Walkthrough

February 20, 2026 · 4 min read · Analysis Notes

The popular alignment tool STAR has now reached version 2.7.11b. However, after updating the other day, I hit this error when trying to run it:

Transcriptome.cpp:18:Transcriptome: exiting because of INPUT FILE error: could not open input file /geneInfo.tab

Judging by the message, it looks like an index-related issue. Could the old index be incompatible with the new version? Time to investigate — let's start from scratch by building the reference genome.

Downloading the Reference Genome

First, download the reference genome. For human and mouse, the most authoritative source is GENCODE. Other popular alternatives such as Ensembl, NCBI RefSeq, and UCSC are also perfectly fine — pick whichever you prefer.

For annotation files, the general recommendation is to download the 4th or 6th option — "Basic Gene Annotation":

wget https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_human/release_47/gencode.v47.primary_assembly.basic.annotation.gtf.gz
# Decompress
gunzip gencode.v47.primary_assembly.basic.annotation.gtf.gz

Which FASTA to download depends on your needs. In most cases, you want the last option — "Genome sequence, primary assembly" — i.e., the full genome. STAR aligns to the genome by default, which allows it to detect alternative splicing events. If you don't need that and only want to align to the transcriptome, download the first option ("Transcript Sequences") and add --genomeType Transcriptome when running STAR.

wget https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_human/release_47/GRCh38.primary_assembly.genome.fa.gz
# Decompress
gunzip GRCh38.primary_assembly.genome.fa.gz

Building the Index

I double-checked the official documentation — the command for this step hasn't changed:

STAR --runMode genomeGenerate \
  --genomeDir GRCh38_genome \
  --genomeFastaFiles GRCh38.primary_assembly.genome.fa \
  --sjdbGTFfile gencode.v47.primary_assembly.basic.annotation.gtf \
  --runThreadN 12 \
  --sjdbOverhang 149  # read length - 1

After completion, I verified the index directory:

/Users/miana/Desktop/GRCh38_genome
├── Genome
├── Log.out
├── SA
├── SAindex
├── chrLength.txt
├── chrName.txt
├── chrNameLength.txt
├── chrStart.txt
├── exonGeTrInfo.tab
├── exonInfo.tab
├── geneInfo.tab
├── genomeParameters.txt
├── sjdbInfo.txt
├── sjdbList.fromGTF.out.tab
├── sjdbList.out.tab
└── transcriptInfo.tab

1 directory, 16 files

Everything looks correct — all expected files are present and no errors were reported. Alright, let's try running the alignment again!

Alignment

STAR --runThreadN 12 \
     --readFilesIn sample1_R1_001.fastq.gz sample1_R2_001.fastq.gz \
     --genomeDir GRCh38_genome \
     --outSAMtype BAM SortedByCoordinate \
     --outSAMunmapped Within \
     --quantMode GeneCounts \
     --sjdbGTFfile gencode.v47.primary_assembly.basic.annotation.gtf \
     --sjdbOverhang 149 \
     --outFileNamePrefix outs \
     --readFilesCommand "gunzip -c"

And… it crashed with the same error again:

Transcriptome.cpp:18:Transcriptome: exiting because of INPUT FILE error: could not open input file /geneInfo.tab
Solution: check that the file exists and you have read permission for this file
SOLUTION: utilize --sjdbGTFfile /path/to/annotations.gtf option at the genome generation step or mapping step

Jan 24 20:14:23 ...... FATAL ERROR, exiting

OK, so clearly this isn't a user error. Digging through GitHub issues, I discovered that this problem was first reported as far back as September 2023:

People were still actively discussing workarounds at the end of 2024:

To summarize: the root cause is Apple Silicon (M-chip) incompatibility (what did we Mac users ever do to deserve this? 😭), and as of now there is still no official fix. After scouring community suggestions and a fair amount of trial-and-error, I finally got it working. Here's the complete process:

Detailed Debugging Steps

⚠️ Warning: Modifying the source code may introduce other unforeseen issues. This is only a temporary workaround — proceed with caution.

Clone the v2.5.11b pre-release from GitHub:

git clone https://github.com/dobinlab/STAR_pre_releases.git

After cloning, don't compile right away. First, open the file ParametersGenome.cpp and find line 27:

transform.outYes = transform.outSAM = transform.outSJ = false;

Change it to:

transform.outYes = transform.outSAM = transform.outSJ = transform.outQuant = false;

Next, open SharedMemory.cpp and replace SHM_NORESERVE with MAP_NORESERVE on lines 109 and 254. Without this change, compilation will fail with the following errors (hat tip to the community members who debugged this one for us 🙏):

SharedMemory.cpp: In member function 'void SharedMemory::CreateAndInitSharedObject(size_t)':
SharedMemory.cpp:109:59: error: 'SHM_NORESERVE' was not declared in this scope; did you mean 'MAP_NORESERVE'?
  109 | _shmID=shmget(_key, toReserve, IPC_CREAT | IPC_EXCL | SHM_NORESERVE | 0666);
      |                                                        ^~~~~~~~~~~~~
      |                                                        MAP_NORESERVE
SharedMemory.cpp: In member function 'void SharedMemory::EnsureCounter()':
SharedMemory.cpp:254:72: error: 'SHM_NORESERVE' was not declared in this scope; did you mean 'MAP_NORESERVE'?
  254 | _sharedCounterID=shmget(_counterKey, 1, IPC_CREAT | IPC_EXCL | SHM_NORESERVE | 0666);
      |                                                                 ^~~~~~~~~~~~~
      |                                                                 MAP_NORESERVE
make: *** [SharedMemory.o] Error 1

Now you can compile. Important: Do not follow the Mac instructions in the official documentation — those are for Intel chips only.

cd STAR/source
make STAR
# Add to PATH
export PATH=/path/to/STAR/:$PATH
# Or alternatively:
# cp STAR /usr/local/bin

At this point, alignment and quantification should run without errors.

💡 Tip: Before running STAR, set ulimit -n 2048 in your terminal to allow STAR to process multiple chunks simultaneously.

Closing Thoughts

Due to its ARM architecture, Apple Silicon has compatibility issues with quite a few bioinformatics tools. That said, when things do work, performance on M-series chips is often significantly faster than on Linux servers. For this project, I aligned and quantified 27 bulk RNA-seq samples (paired-end, 150 bp reads) using STAR, averaging just 5 minutes per sample. For comparison, I also ran Salmon on the same data — and surprisingly, STAR was actually faster in this case, though Salmon still has a clear advantage in terms of memory usage. I'll do a more detailed comparison of STAR vs. Salmon outputs when I get the chance!

Originally posted on WeChat Official Account: bioinfo_studyroom

Single Cell Upstream Cell Ranger