`Failure getting reference bases` inadequately describes the missing index error

[multimeric]

Description of the issue:

When a CRAM is used as input to htsjdk.samtools.cram.build.CRAMReferenceRegion.fetchReferenceBasesByRegion, and the reference file is missing its index, the error is confusing and doesn't accurately describe the issue. Currently it says something like java.lang.IllegalArgumentException: Failure getting reference bases for sequence chr1.

Your environment:

• version of htsjdk: 4.1.1
• version of java: 22.0.2
• which OS: RedHat Linux 9.1

Steps to reproduce

This error came up when using GATK, so my reproduction example involves the command line. I'm sure it's easy to convert this to a pure Java example however. The reason I am reporting it here is that the error comes from htsjdk and I would like to see it improved in all tools that use it.

Assume that there are only the CRAM and the fasta file in the working directory:

$ ls       
GTEX-111CU-0003-SM-6WBUD.cram  Homo_sapiens_assembly38.fasta

Next, run gatk CollectQualityYieldMetrics -I GTEX-111CU-0003-SM-6WBUD.cram -R Homo_sapiens_assembly38.fasta -O yield_metrics.txt

Expected behaviour

The function should fail with a message specifically saying fasta reference file Homo_sapiens_assembly38.fasta is missing its .fai index. Please run samtools faidx on it.

Actual behaviour

It fails with:

java.lang.IllegalArgumentException: Failure getting reference bases for sequence chr1
        at htsjdk.samtools.cram.build.CRAMReferenceRegion.fetchReferenceBasesByRegion(CRAMReferenceRegion.java:175)
        at htsjdk.samtools.cram.build.CRAMReferenceRegion.fetchReferenceBasesByRegion(CRAMReferenceRegion.java:195)
        at htsjdk.samtools.cram.structure.Slice.normalizeCRAMRecords(Slice.java:450)
        at htsjdk.samtools.cram.structure.Container.getSAMRecords(Container.java:322)
        at htsjdk.samtools.CRAMIterator.nextContainer(CRAMIterator.java:112)
        at htsjdk.samtools.CRAMIterator.hasNext(CRAMIterator.java:204)
        at htsjdk.samtools.SamReader$AssertingIterator.hasNext(SamReader.java:608)
        at picard.analysis.SinglePassSamProgram.makeItSo(SinglePassSamProgram.java:152)
        at picard.analysis.SinglePassSamProgram.doWork(SinglePassSamProgram.java:94)
        at picard.cmdline.CommandLineProgram.instanceMain(CommandLineProgram.java:281)
        at org.broadinstitute.hellbender.cmdline.PicardCommandLineProgramExecutor.instanceMain(PicardCommandLineProgramExecutor.java:37)
        at org.broadinstitute.hellbender.Main.runCommandLineProgram(Main.java:166)
        at org.broadinstitute.hellbender.Main.mainEntry(Main.java:209)
        at org.broadinstitute.hellbender.Main.main(Main.java:306)

[cmnbroad]

Yeah, thats not a helpful error message.