doctor: gate self-test reports 'cannot read mxbuild's error file' when JAVA_HOME is JDK 21 on a Mendix 11.14+ model #576

Activity

1. MendixMau

   added

   needs/triage

   provenance/agent-authored

   kind/bug

   on Oct 26, 2026
2. MendixMau commented on Oct 26, 2026

   

   MendixMau

   on Oct 26, 2026

   OwnerAuthor

   More actions

   Triage: DISCUSS track. Ask 3 changes how every mxbuild call in every entry mode picks Java (find_java precedence), which is a behaviour change for anyone with JAVA_HOME set. Asks 1 and 2 on their own would be FIX track. Verified by code reading against master 6615869; not reproduced here (no mxbuild/JDK 25 in this container).
   Problem: There are two separate defects.

   • The FAIL line hides the cause.
     • bin/doctor.sh:1466 runs base_count=$(mxtk_mxbuild_error_count …) inside a command substitution. The function sets MXTK_MXBUILD_WHY as a global (project-bin/_common.sh:874), but the global dies with the subshell, so doctor cannot print it today.
     • mxbuild's exit 3 with an empty problems[] becomes ?, which :1474 labels "cannot read mxbuild's error file". The real reason, "release version 25 not supported", is lost. The known-bad run at :1519 has the same issue.
   • JAVA_HOME beats the model rule. find_java (_common.sh:615) returns $JAVA_HOME before the 11.13→21 / 11.14→25 rule. find_java_note (:599) also stays silent whenever JAVA_HOME is set. A global JDK 21 therefore breaks every 11.14+ build with no warning, and toolkit.env can't override the shell environment.
     Value: High.
   • macOS users who set JAVA_HOME to dodge the /usr/bin/java stub hang (common, per the report) get a misleading FAIL on every 11.14+ project.
   • Anyone running 11.13 and 11.15 projects side by side cannot satisfy both with one global JAVA_HOME.
     Options:

   1. Doctor diagnostics only (asks 1+2).
      • Pass the 3rd errors-file argument at :1466/:1512 and read errors[].message from that file, so the cause survives the subshell. Put it in the FAIL line, e.g. "mxbuild refused the model before checking it: release version 25 not supported".
      • In "Build toolchain" (:669), compare the JAVA_HOME major with _mxtk_java_want and WARN with the fix.
      • No change to find_java, nothing new blocks, and it costs one extra java -version in doctor only. All entry modes are unaffected outside doctor.
   2. Option 1, plus an explicit MXTK_JAVA_HOME override that find_java checks before JAVA_HOME. It can be set per project in toolkit.env, so mixed-version machines work.
      • It is opt-in: nobody's resolution changes unless they set it.
      • Small risk: one more resolution path to document in toolkit.env docs.
      • Performance is unchanged.
   3. Option 1, plus automatic precedence: find_java ignores an environment JAVA_HOME whose major doesn't match the model and uses java_home -F -v <want> instead (macOS).
      • It fixes the case without any user action, but it silently overrides an explicit user setting, and it needs a JDK version probe on every mxbuild call (a small cost on each exec.sh/gate run).
      • It is mac-only in practice, since Windows/Linux have no java_home.
        Recommendation: Option 2.

   • Option 1 is clearly needed: a FAIL that names the wrong cause sends people into the gate code.
   • An opt-in per-project override solves the side-by-side case without overriding anyone's explicit JAVA_HOME behind their back.
   • Option 3's silent override is the kind of hidden precedence that makes Java issues hard to diagnose.
   • Proof for any option: a test-doctor-gate-selftest.sh case with a fake mxbuild that exits 3 and writes errors[], asserting the message appears in the FAIL line (it fails on master). For option 2, add a find_java case for MXTK_JAVA_HOME.
     Decision needed from you: Should the toolkit stop at better diagnostics (1), add an opt-in per-project Java override (2), or auto-override a wrong-major JAVA_HOME (3)? Reply "go option N" to build it.

   ---

   Generated by Claude Code
3. MendixMau

   added 3 commits that reference this issue on Oct 26, 2026

   fix(doctor, exec): name the env file JAVA_HOME came from; failed-exec…

   ...

   379289a

   fix(doctor): name the env file JAVA_HOME came from only when it did

   ...

   38c8b15

   Bug sweep 2026-10-26: gates, runners, doctor, lint receipt, git hooks…

   ...

   a088b4e
4. MendixMau commented on Oct 26, 2026

   

   MendixMau

   on Oct 26, 2026

   OwnerAuthor

   More actions

   Asks 1 and 2 are fixed in #578 (squash a088b4e):

   • the self-test quotes mxbuild's real reason, including the javac error: line;
   • doctor WARNs when the JDK major doesn't match a Mendix 11 model, and names the file JAVA_HOME came from.

   Ask 3 (a MXTK_JAVA_HOME override) is on the roadmap: #579.

   ---

   Generated by Claude Code
5. MendixMau

   closed this as completedon Oct 26, 2026