Troubleshooting

RNA-seq Troubleshooting Notes

Short problem-cause-fix notes for the issues most likely to interrupt the upstream RNA-seq workflow.

Problem	Likely cause	Fix
STAR not reading input reads	Incorrect file paths, wrong compression handling, or mismatched input flags.	Check the exact FASTQ filenames, confirm the files exist, and use the correct read command for compressed files.
Platform-specific issues on Mac arm64	Binary compatibility or tool-installation differences across architectures.	Use Conda-installed packages where possible and switch to a tool that runs cleanly in the local environment if needed.
Why switching tools is sometimes necessary	The original planned workflow may not be the most reliable option on the current machine.	Keep the original workflow documented for learning, but use the practical toolchain that executes correctly for the local tutorial run.
Common file path mistakes	Running commands from the wrong directory or using incomplete relative paths.	Run `pwd`, inspect folders with `ls`, and prefer clear project-relative paths throughout the workflow.
Common folder naming mistakes	Outputs are directed to folders that do not exist or are named differently from the command.	Create all expected folders with `mkdir -p` before running alignment or counting steps.
Missing output directory errors	The tool tries to write to a directory that has not been created yet.	Create the target folder first and rerun the command with the same output path.
Annotation and genome version mismatch	The FASTA and GTF files come from different genome builds or releases.	Download a matched genome FASTA and annotation GTF from the same source and release.
Low alignment rate	Poor read quality, wrong reference, contamination, or library-specific issues.	Review FastQC, confirm the sample species and reference build, and verify trimming and file pairing.
`featureCounts` returns unexpected counts	Incorrect annotation, wrong strandedness setting, or low-quality alignment output.	Recheck the GTF file, confirm library type, and inspect the sorted BAM file before counting again.