GATK简介与常见报错概述
大家好，我是老张，做了将近六年的生物信息学，其中一大半时间都在跟GATK打交道。说实话，刚入行那会儿，每天看到崩溃日志就想砸键盘。后来摸索出一套排查套路，现在团队里新同事遇到报错，基本上按我这个思路几分钟就能定位。
GATK全称是Genome Analysis Toolkit，Broad Institute开发的基因组分析工具集。它最核心的功能就是变异检测——从测序数据里找出SNP、Indel这些变异位点。但你想想看，测序数据本身就有各种偏差，加上GATK的算法又复杂，稍微有点不对头就会报错。我在项目中遇到过因为一个换行符不一致导致整个流程死掉的，也遇到过因为Java内存参数写错运行了三天全白费的情况。
这章咱们先搭个框架，搞清楚GATK到底在做什么，以及常见的报错长什么样。心里有张图，后面排查才会快。
GATK的典型工作流
GATK团队自己推荐的最佳实践流程，我一般把它分成五个阶段。你看这个图就清楚了：
这个流程图看着简单，但每个环节都可能出问题。我习惯把报错先按「阶段」分，再按「错误类型」查，这样不会乱。
GATK主要工具模块
GATK的工具有几十个，但日常高频使用的就这些。我列了个表，你对照着看：
| 工具名称 | 所属阶段 | 主要用途 |
|---|---|---|
| MarkDuplicates | 预处理 | 标记PCR重复 reads |
| BaseRecalibrator | 预处理 | 碱基质量校准 |
| ApplyBQSR | 预处理 | 应用校准结果 |
| HaplotypeCaller | 变异检测 | GVCF模式下的SNP/Indel检测 |
| Mutect2 | 变异检测 | 肿瘤-正常配对体细胞变异检测 |
| VariantRecalibrator | 过滤 | VQSR训练模型 |
| ApplyVQSR | 过滤 | 应用VQSR过滤 |
| Funcotator | 注释 | 变异功能注释 |
个人小技巧：我每次写新流程前，都会先看一眼官方文档里的tool maturity标签。有些工具标注了"Beta"或"Experimental"，我个人建议别在生产环境里直接用，坑太多。
常见报错类型概览
我从过去几百次报错里归纳了五大类。你看看你遇到的是哪种：
- 输入数据错误——FASTQ质量太低、BAM文件损坏、参考基因组版本不匹配。这是最频繁的一类。
# 常见日志样本 ERROR: SAMFileReader: SAM file has no records WARNING: Reference sequence does not match expected - 资源/内存错误——Java堆内存不够、磁盘空间满、线程数不足。
# 经典报错 java.lang.OutOfMemoryError: Java heap space - 参数配置错误——-R、-I等输入参数写错路径、区间文件格式不对、线程数设成负数（真有人这么干）。
- 依赖/版本错误——GATK版本与Picard版本不兼容、Java版本太高或太低。
# 版本错误示例 Error: GATK requires Java 11 or later - 运行环境错误——集群调度器作业脚本写错、环境变量没设、conda环境冲突。
你可能会问，为什么GATK这么容易报错？说白了，因为它的输入数据要求极其严格。比如BAM的header里必须包含正确的参考基因组MD5，读组信息必须完整，排序顺序必须一致。任何一个细节没对齐，它就直接罢工。我刚开始用那会儿，光一个"Sort order"不一致的问题就折腾了两天。
避坑指南：我曾经因为贪方便把不同测序平台的BAM直接合并，结果HaplotypeCaller跑到一半报错说"Read groups not unique"。后来花了半天重新拆分、加标记。记住：每个sample的read group必须唯一，且与BAM header里的信息一致。
排查思路框架
遇到报错别慌，按这三步来：
- 第一步，看日志关键词。GATK的日志非常详细，错误类型会直接写在第一行。比如"WARN"开头的是警告，可以忽略；"ERROR"开头就必须处理。我经常用
grep -i error先过滤一遍。 - 第二步，定位阶段和工具。日志里会显示运行的是哪个工具。拿前面的流程表一对照，就知道是预处理、检测还是过滤阶段出的问题。
- 第三步，对照经验库。后面几章我会把每个阶段最常见的报错拆开来讲。你只要记住对应的错误代码，直接翻到对应章节查解决办法就行。
举个例子，你看到这样的日志：
## ERROR MESSAGE: GATK 4.2.2.0
## Error: File /data/sample.bam does not exist or is not readable
很明显是输入文件路径问题，属于第一类输入错误。检查路径权限、文件名、是否被移动过——大概率五分钟解决。
经验之谈：我建议每个GATK流程里都加上--verbosity MINIMAL参数，这样日志只输出ERROR级别的信息，不会被一堆INFO刷屏。排查效率能提高一大截。
好了，这一章咱们把GATK的流程、工具、报错类型和排查思路理清楚了。后面每章都会针对一个具体的错误场景，从“为什么出现”到“怎么解决”手把手教你。你在实际项目中遇到的具体报错，基本都能在后面的章节里找到对应解法。