生信常见报错排查：20条错误与解决方案

生信分析中报错种类繁多——文件权限、内存溢出、软件依赖、流程逻辑。本文按 文件/权限 → 内存/OOM → 软件/依赖 → R/Python → 流程逻辑 分类，整理 20 个常见错误，每条附错误原文、原因分析和解决方案。

全部在 Debian 13 上复现并验证。

一、文件与权限类#

错误1：`Permission denied`#

1
bash: ./run_pipeline.sh: Permission denied

原因： 文件没有执行权限。

排查：

1
ls -la run_pipeline.sh
2
# -rw-r--r-- 1 user user 1234 Mar 1 10:00 run_pipeline.sh
3
#  ^ 没有 x（执行位）

解决：

1
chmod +x run_pipeline.sh

如果是从 Windows 传过来的脚本，还要检查换行符：

1
# 查看是否有 ^M（\r）换行符
2
cat -A run_pipeline.sh | head -5
3

4
# 转换
5
sed -i 's/\r$//' run_pipeline.sh

错误2：`No such file or directory`#

1
$ samtools view -bS alignment.sam
2
[E::hts_open_format] Failed to open file "alignment.sam" : No such file or directory

排查清单（按顺序）：

1
# 1. 文件真的不存在？
2
ls -la alignment.sam
3

4
# 2. 你在正确的目录吗？
5
pwd
6

7
# 3. 文件名拼错了？（大小写！）
8
ls -la Ali*   # 检查是否有大小写差异
9

10
# 4. 路径有空格或特殊字符？
11
# 永远用双引号包裹路径
12
samtools view -bS "alignment.sam"

最常见的原因： 上一步的输出写到了另一个目录，或者文件名带了 _sorted 后缀而你没注意到。

错误3：`No space left on device`#

1
$ gzip raw_data.fastq
2
gzip: raw_data.fastq: No space left on device

排查：

1
df -h .
2
# Filesystem      Size  Used Avail Use% Mounted on
3
# /dev/sda1        97G   93G   0   100% /opt/data
4

5
# 找大文件
6
du -sh /opt/data/* | sort -rh | head -20

解决：

1
# 紧急清理（删除 conda 缓存）
2
conda clean --all -y
3

4
# 清理临时文件
5
rm -rf /tmp/bioinfo_* /tmp/samtools_*
6

7
# 清理旧日志
8
find . -name "*.log" -mtime +30 -delete

错误4：软链接断掉（broken symbolic link）#

1
$ ls -la reference/hg38.fa
2
lrwxrwxrwx 1 user user 42 Mar 1 10:00 reference/hg38.fa -> ../../old_path/hg38.fa
3
# 文件显示红色（在 ls --color 中），说明目标不存在

排查：

1
readlink -f reference/hg38.fa   # 空输出表示断了
2
ls -laL reference/hg38.fa        # -L 会报错如果断了

解决： 重新创建链接或直接放文件副本。

1
# 不要用软链接管理大参考基因组——用硬链接或直接复制
2
ln -f /opt/refs/GRCh38.primary.fa reference/hg38.fa  # 硬链接
3
# 或
4
cp /opt/refs/GRCh38.primary.fa reference/hg38.fa

二、内存与系统资源类#

错误5：`Killed`（OOM Killer）#

1
$ STAR --genomeDir star_index --readFilesIn sample.fastq.gz
2
... running for 2 hours ...
3
Killed

这是 Linux 内核的 OOM（Out of Memory）Killer。当系统内存耗尽时，内核会杀死占用内存最大的进程。

排查：

1
# 事后检查
2
dmesg | grep -i "out of memory" | tail -20
3
dmesg | grep -i "killed process" | tail -10
4

5
# 会看到类似：
6
# Out of memory: Killed process 28473 (STAR) total-vm:52GB ...

解决：

1
# 方案1：加内存（废话但有效）
2
# 方案2：减少线程（线程越多内存越大，不是线性关系！）
3
STAR --runThreadN 4 ...   # 从 16 降到 4
4

5
# 方案3：限制 STAR 内存
6
STAR --limitBAMsortRAM 10000000000 ...  # 限制排序内存 10GB
7

8
# 方案4：用 swap（临时救急）
9
sudo fallocate -l 32G /swapfile
10
sudo chmod 600 /swapfile
11
sudo mkswap /swapfile
12
sudo swapon /swapfile

软件	每线程内存	建议线程数
STAR	~30-40GB (人类)	4-8
HISAT2	~8-10GB	8-16
Bowtie2	~4GB	8-16
BWA-MEM	~6-8GB	8-12

错误6：`Bus error (core dumped)`#

1
$ hisat2 -x genome_index -1 R1.fq -2 R2.fq -S output.sam
2
Bus error (core dumped)

原因： 内存硬件故障或文件读取越界。生信中常见于索引文件损坏。

排查：

1
# 1. 检查索引完整性
2
md5sum genome_index.*.ht2
3
# 与官网提供的 md5 对比
4

5
# 2. 重建索引
6
hisat2-build reference.fa genome_index

错误7：`Too many open files`#

1
$ parallel -j 50 samtools sort ...
2
/bin/bash: error while loading shared libraries: libtinfo.so.6:
3
cannot open shared object file: Too many open files

原因： Linux 限制每个进程可同时打开的文件数（默认 1024）。生信并行任务频繁触发。

解决：

1
# 查看当前限制
2
ulimit -n
3
# 1024
4

5
# 临时提升
6
ulimit -n 65536
7

8
# 永久生效（/etc/security/limits.conf）
9
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
10
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

错误8：`GLIBCXX_3.4.30 not found`#

1
$ samtools
2
samtools: /lib/x86_64-linux-gnu/libstdc++.so.6: version `GLIBCXX_3.4.30' not found

原因： Conda 装的包动态链接了新版 libstdc++，但系统里的是旧版。

排查：

1
# 看系统和 conda 各有什么版本的 GLIBCXX
2
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX | tail -5
3
strings $CONDA_PREFIX/lib/libstdc++.so.6 | grep GLIBCXX | tail -5

解决：

1
# 临时：让程序优先用 conda 的库
2
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH
3

4
# 根本：在 conda 环境内装 libstdcxx-ng
5
mamba install -c conda-forge libstdcxx-ng -y

三、软件与依赖类#

错误9：`samtools: command not found`#

1
$ samtools view
2
-bash: samtools: command not found

原因： 没装或环境没激活。

排查三步走：

1
# 1. 检查环境是否激活
2
conda env list | grep '*'
3
# 如果 base 前面没有 *，说明 conda 没 init
4

5
# 2. 用 which 定位
6
which samtools  # 无输出 = 没装
7

8
# 3. 检查是否在正确环境里
9
conda list | grep samtools

错误10：conda 装包卡住 `Solving environment`#

参见 Conda环境冲突全攻略第 7 节。核心解决：

1
# 把 conda 换成 mamba
2
mamba install -c bioconda package_name -y
3

4
# 或者指定精确版本缩小搜索空间
5
mamba install -c bioconda package_name=1.2.3 -y

错误11：pip 覆盖了 conda 的包#

1
$ conda install -c conda-forge numpy
2
$ pip install scikit-learn  # pip 升级了 numpy
3
$ python -c "import numpy; print(numpy.__version__)"
4
# numpy 崩溃或版本回退

解决： 优先用 conda 装所有依赖；必须用 pip 时加 --no-deps：

1
pip install --no-deps scikit-learn

如果已经崩了，重建环境：

1
mamba env remove -n myenv
2
mamba create -n myenv -c conda-forge python=3.10 numpy scipy pandas matplotlib -y
3
pip install --no-deps scikit-learn

错误12：Java 版本不兼容（Picard/GATK）#

1
$ java -jar picard.jar MarkDuplicates ...
2
Error: A JNI error has occurred, please check your installation
3
Exception in thread "main" java.lang.UnsupportedClassVersionError

原因： Picard/GATK 需要特定 Java 版本。Picard 2.27+ 需要 Java 17。

排查：

1
java -version
2
# openjdk version "11.0.21"  <- 太旧了

解决：

1
mamba install -c conda-forge openjdk=17 -y
2
java -version  # 确认版本

四、R 语言类#

错误13：`there is no package called 'xxx'`#

1
> library(DESeq2)
2
Error in library(DESeq2) : there is no package called 'DESeq2'

解决三步走：

1
# 1. 检查是否装过
2
installed.packages()[,"Package"] %>% grep("DESeq2", ., value = TRUE)
3

4
# 2. 没装就装
5
if (!requireNamespace("BiocManager", quietly = TRUE))
6
    install.packages("BiocManager")
7
BiocManager::install("DESeq2")
8

9
# 3. 确认 .libPaths()——你可能装了但 R 找不到
10
.libPaths()
11
# 如果 conda 环境里的 R 在用系统的 library path，修正：
12
# export R_LIBS_USER=$CONDA_PREFIX/lib/R/library

错误14：`cannot allocate vector of size X Gb`#

1
> deseq2_results <- DESeq(dds)
2
Error: cannot allocate vector of size 8.5 Gb

原因： R 默认把所有数据装入内存。

解决：

1
# 方案1：写一个 swap 文件（给 Linux 额外虚拟内存）
2
sudo fallocate -l 32G /swapfile
3
sudo mkswap /swapfile && sudo swapon /swapfile
4

5
# 方案2：减少数据量（预过滤低表达基因）
6
keep <- rowSums(counts(dds) >= 10) >= 3
7
dds <- dds[keep, ]
8

9
# 方案3：用内存友好的替代
10
# Seurat 用 BPCells，DESeq2 没有——只能加内存或过滤

错误15：R 版本与包不兼容#

1
> install.packages("tidyverse")
2
ERROR: this R is version 4.2.3, package 'tidyverse' requires R >= 4.3

解决：

1
# conda 环境里升级 R
2
mamba install -c conda-forge r-base=4.3 -y
3

4
# 或者用 conda 装匹配版本的包（conda 会处理好 R 版本）
5
mamba install -c conda-forge r-tidyverse -y

错误16：Bioconductor 版本不匹配#

1
> BiocManager::install("DESeq2")
2
Error: Bioconductor version 3.16 (R 4.2) is not compatible with R 4.3

解决：

1
# 升级 Bioconductor 到与 R 匹配的版本
2
BiocManager::install(version = "3.18")  # R 4.3 对应 3.18
3

4
# 对照表：
5
# R 4.2 → Bioc 3.16
6
# R 4.3 → Bioc 3.18
7
# R 4.4 → Bioc 3.19

五、流程逻辑与数据类#

错误17：BAM 的 Read Group 缺失#

1
$ gatk HaplotypeCaller -R ref.fa -I sample.bam -O variants.vcf
2
A USER ERROR has occurred: Read groups are missing in the BAM file

解决： 比对时就用 -R 加 Read Group 信息。

1
# BWA-MEM
2
bwa mem -R '@RG\tID:sample1\tSM:sample1\tPL:ILLUMINA' ref.fa R1.fq R2.fq > aln.sam
3

4
# STAR
5
STAR --outSAMattrRGline ID:sample1 SM:sample1 PL:ILLUMINA ...
6

7
# 也可以事后补（samtools addreplacerg）
8
samtools addreplacerg -r '@RG\tID:sample1\tSM:sample1' -o fixed.bam original.bam

错误18：featureCounts 分配的 reads 数异常低#

1
$ featureCounts -a genes.gtf -o counts.txt sample.bam
2
# Successfully assigned: 12.3%  ← 太低！

正常 RNA-seq 的分配率应该 >70%（人类/小鼠）。排查：

1
# 1. BAM 和 GTF 的染色体名一致吗？
2
samtools idxstats sample.bam | head -5
3
grep -oP '^chr[^"]+' genes.gtf | sort -u | head -5
4
# chr1 vs 1 ——这就是问题！BAM 是 chr1，GTF 是 1
5

6
# 2. GTF 和 BAM 的 strand 信息一致吗？
7
# featureCounts 默认 -s 0（unstranded）
8
# 如果你的数据是 stranded 但 GTF 没标注，用 -s 2
9
featureCounts -s 2 -a genes.gtf -o counts.txt sample.bam

错误19：DESeq2 的 `model matrix is not full rank`#

1
> dds <- DESeq(dds)
2
Error: the model matrix is not full rank

原因： 实验设计矩阵中存在线性依赖。最常见：某个 factor 的所有样本和另一个 factor 完全一致。

排查：

1
# 查看 design formula 的混淆
2
table(dds$condition, dds$batch)
3
# 如果你看到类似：
4
#         batch1 batch2
5
#   ctrl      3      0
6
#   treat     0      3
7
# 这意味着 condition 和 batch 完全混淆——DESeq2 无法区分

解决： 调整 design formula 去掉混淆的项，或合并 factor。

1
# 如果 batch 和 condition 不混淆，把 design 改成
2
design(dds) <- ~ batch + condition

1
$ samtools index sample.bam
2
[E::hts_idx_push] Unsorted positions on sequence chr1

原因： BAM 没排序或排序参数不对。

解决：

1
# 按坐标排序
2
samtools sort -o sample_sorted.bam sample.bam
3
samtools index sample_sorted.bam
4

5
# 如果要按名字排序（某些工具需要）
6
samtools sort -n -o sample_qname.bam sample.bam

六、通用排查技巧#

技巧1：看日志的最后一行#

1
# 大多数生信工具的最后一行是总结或错误码
2
tail -5 pipeline.log
3

4
# 如果只有 Killed，看 dmesg
5
dmesg | tail -30 | grep -iE "error|killed|oom|fail"

技巧2：检查退出码#

1
# 脚本里加这行
2
some_command
3
echo "Exit code: $?"
4
# 0 = 成功，1 = 通用错误，134 = SIGABRT，137 = SIGKILL（OOM），139 = SIGSEGV

技巧3：临时文件残留#

1
# 生信软件经常在 /tmp 下创建临时文件，崩溃后不清理
2
ls -la /tmp/samtools_* /tmp/STAR_* /tmp/hisat2_*
3

4
# 清理（谨慎！）
5
find /tmp -maxdepth 1 -name 'samtools_*' -mtime +1 -delete
6
find /tmp -maxdepth 1 -name 'STAR_*' -mtime +1 -delete

技巧4：环境变量问题#

1
# 很多生信软件通过环境变量指定参考基因组等配置
2
echo $BOWTIE2_INDEXES
3
echo $STAR_GENOME_DIR
4

5
# 如果为空且工具报 "index not found"，在 ~/.bashrc 里加：
6
export BOWTIE2_INDEXES="/opt/refs/bowtie2"

本文覆盖了 20 个常见生信错误。如果你遇到了不在列表中的报错，把错误信息丢给搜索引擎 + “biostars” 或 “seqanswers”，大概率能找到。

本文于 2025-09-05 在 Debian 13 上复现验证。

一、文件与权限类#

错误1：`Permission denied`#

错误2：`No such file or directory`#

错误3：`No space left on device`#

错误4：软链接断掉（broken symbolic link）#

二、内存与系统资源类#

错误5：`Killed`（OOM Killer）#

错误6：`Bus error (core dumped)`#

错误7：`Too many open files`#

错误8：`GLIBCXX_3.4.30 not found`#

三、软件与依赖类#

错误9：`samtools: command not found`#

错误10：conda 装包卡住 `Solving environment`#

错误11：pip 覆盖了 conda 的包#

错误12：Java 版本不兼容（Picard/GATK）#

四、R 语言类#

错误13：`there is no package called 'xxx'`#

错误14：`cannot allocate vector of size X Gb`#

错误15：R 版本与包不兼容#

错误16：Bioconductor 版本不匹配#

五、流程逻辑与数据类#

错误17：BAM 的 Read Group 缺失#

错误18：featureCounts 分配的 reads 数异常低#

错误19：DESeq2 的 `model matrix is not full rank`#

错误20：SAM/BAM 的 header 错乱导致下游崩溃#

六、通用排查技巧#

技巧1：看日志的最后一行#

技巧2：检查退出码#

技巧3：临时文件残留#

技巧4：环境变量问题#

文章分享

文章目录

生信常见报错排查：20条错误与解决方案

一、文件与权限类#

错误1：Permission denied#

错误2：No such file or directory#

错误3：No space left on device#

错误4：软链接断掉（broken symbolic link）#

二、内存与系统资源类#

错误5：Killed（OOM Killer）#

错误6：Bus error (core dumped)#

错误7：Too many open files#

错误8：GLIBCXX_3.4.30 not found#

三、软件与依赖类#

错误9：samtools: command not found#

错误10：conda 装包卡住 Solving environment#

错误11：pip 覆盖了 conda 的包#

错误12：Java 版本不兼容（Picard/GATK）#

四、R 语言类#

错误13：there is no package called 'xxx'#

错误14：cannot allocate vector of size X Gb#

错误15：R 版本与包不兼容#

错误16：Bioconductor 版本不匹配#

五、流程逻辑与数据类#

错误17：BAM 的 Read Group 缺失#

错误18：featureCounts 分配的 reads 数异常低#

错误19：DESeq2 的 model matrix is not full rank#

错误20：SAM/BAM 的 header 错乱导致下游崩溃#

六、通用排查技巧#

技巧1：看日志的最后一行#

技巧2：检查退出码#

技巧3：临时文件残留#

技巧4：环境变量问题#

文章分享

文章目录

错误1：`Permission denied`#

错误2：`No such file or directory`#

错误3：`No space left on device`#

错误5：`Killed`（OOM Killer）#

错误6：`Bus error (core dumped)`#

错误7：`Too many open files`#

错误8：`GLIBCXX_3.4.30 not found`#

错误9：`samtools: command not found`#

错误10：conda 装包卡住 `Solving environment`#

错误13：`there is no package called 'xxx'`#

错误14：`cannot allocate vector of size X Gb`#

错误19：DESeq2 的 `model matrix is not full rank`#