Analysis timeout terminates the Qodana run mid-inspection — graceful cancellation remains unresolved

Question

Running Qodana in CI calls for a hard ceiling on analysis time. The documented run.timeout option in qodana.yaml (mirrored by a --timeout CLI flag) provides one: when the limit expires, the run stops with a non-zero exit code and a partial report. The open design problem is making that termination — and SIGTERM-based job cancellation — behave gracefully rather than abruptly.

Two constraints shape the question. The timeout governs the whole analysis process, not individual inspections, while the quality gate evaluation runs afterwards, outside that budget. Behavior also appears to differ between CLI and Docker distributions because the image entrypoint may add its own signal handling, and default timeout values seem to have shifted across 2024.x releases — worth confirming against whichever image tag is pinned.

Three points need clarification:

When the timeout expires, does Qodana interrupt the in-flight inspection at a safe point or terminate the JVM immediately — and is the timeout exit code distinguishable from a quality gate failure?
Does SIGTERM from a cancelled CI job propagate through the Docker entrypoint so caches are flushed and temporary directories such as /tmp/qodana-* are cleaned up?
Should a CI-level job timeout be sized as analysis timeout plus quality gate time, or is there a documented mechanism that covers both phases under one limit?

Tasadduq Burney · Answer

Answer to the Three Core Questions
1. What happens when the timeout expires?

The run.timeout setting (or --timeout flag) triggers a SIGTERM to the JVM that hosts Qodana.
Qodana does not wait for the current inspection to reach a natural boundary; the JVM may terminate immediately, aborting any in‑flight check.
Upon termination the process exits with code 1, which is distinct from the quality‑gate failure code (typically 2).

2. Does SIGTERM from a cancelled CI job reach Qodana in Docker?

Docker’s default entrypoint can intercept SIGTERM. If it does not forward the signal to the child process, the JVM will not receive it and temporary directories such as /tmp/qodana‑* may remain.
Use docker run --sig-proxy=true or provide a minimal entrypoint that forwards signals:
#!/usr/bin/env bash
set -e
# Forward SIGTERM to the child
trap 'kill -TERM $PID' TERM
java -jar qodana.jar "$@" & PID=$!
wait $PID

3. How should a CI job timeout be sized?

There is no single flag that covers both the analysis phase and the subsequent quality‑gate evaluation. The run.timeout only limits the analysis.
Set the CI job timeout to at least run.timeout + buffer (e.g., 30 s buffer) to allow Qodana to finish the gate check and emit the final report.
Optionally, run Qodana twice: once with --timeout and once with --gate only, if your pipeline supports separate stages.

Practical Verification Steps

Run a scan with an intentionally short timeout:
qodana scan --timeout 5

Check that the exit code is 1 and the log contains a line such as Analysis timed out after 5s.
After termination, list the temporary directory:
ls /tmp | grep qodana

If you see qodana-xxxx leftovers, you need to ensure signal forwarding in Docker.
Run the same scan inside Docker with signal proxying:
docker run --rm --sig-proxy=true ghcr.io/jetbrains/qodana:2025.1 scan --timeout 5

Verify that the temp directory is cleaned up after the container exits.
Repeat the above tests on the specific Qodana version/tag you use to confirm version‑specific behavior.

What Information Is Still Needed?
To give a version‑specific recommendation, I need to know the exact Qodana image tag or binary version you are running. Different releases have minor changes in default timeout values and signal handling.
Could you share the tag (e.g., 2025.1 or 2024.2) or the output of qodana --version?

Analysis timeout terminates the Qodana run mid-inspection — graceful cancellation remains unresolved

1 answer

Answer to the Three Core Questions

Practical Verification Steps

What Information Is Still Needed?

Your perspective belongs here.

0 question comments