Skip to content

Work around scaladoc JIT NPE on JDK 25#160

Merged
ghostdogpr merged 1 commit into
mainfrom
fix/scaladoc-jit-npe
Jul 3, 2026
Merged

Work around scaladoc JIT NPE on JDK 25#160
ghostdogpr merged 1 commit into
mainfrom
fix/scaladoc-jit-npe

Conversation

@ghostdogpr

Copy link
Copy Markdown
Owner

Root cause

The publish job (and, since #159 added opentelemetry/doc, the docs job) fails with a scaladoc crash:

java.lang.NullPointerException: ... the return value of
"dotty.tools.scaladoc.translators.SignatureBuilder.content()" is null
    at ...SignatureBuilder.termParamList

This is scala/scala3#24183: on JDK 25 the C2 JIT miscompiles a combinator in scaladoc's SignatureBuilder, so content() returns null once that method gets JIT-compiled. That only happens after the method is warmed up by several doc runs in one JVM, which is why it hit a random cell and only in the many-cell ci-release / docAll runs, not standalone. Started when CI moved to Temurin 25. Fixed upstream in Scala 3.9.0 (scala/scala3#25779).

Confirmed locally: with C2 disabled (-XX:TieredStopAtLevel=1) or the offending class excluded from JIT, docAll goes from reliably crashing to 0 crashes.

Changes

  • .jvmopts: exclude dotty.tools.scaladoc.translators.SignatureBuilder from JIT. sbt reads .jvmopts on every invocation, so this covers both the docs and publish jobs (and local doc/publishLocal) with C2 left on everywhere else. Harmless where scaladoc isn't loaded.
  • build.sbt: remove the doc-task serialization from Serialize scaladoc during publish and fix opentelemetry doc links #159 (scaladocTag, concurrentRestrictions, the Compile / doc tag). It was based on a wrong concurrency hypothesis and had no effect — the crash reproduces with doc tasks run strictly serially.

Verification

  • sbt docAll on a clean fresh JVM: 0 crashes across two trials (previously ~reliably crashed), and the docs-gate warning grep passes.
  • Confirmed via RuntimeMXBean that the .jvmopts flag actually reaches the sbt JVM.
  • scalafmtSbtCheck passes.

The publish job's scaladoc crashes with a SignatureBuilder NPE
(scala/scala3#24183): on JDK 25 the C2 JIT miscompiles a combinator so
content() returns null once the method is compiled, after several doc
runs warm it up in one JVM. It is not a concurrency race, so the doc-task
serialization added earlier had no effect; drop it and exclude the
offending scaladoc class from JIT via .jvmopts instead. Fixed upstream in
Scala 3.9.0 (scala/scala3#25779).
@ghostdogpr ghostdogpr merged commit 4bfb4c4 into main Jul 3, 2026
9 checks passed
@ghostdogpr ghostdogpr deleted the fix/scaladoc-jit-npe branch July 3, 2026 01:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant