diff --git a/test/sageclient/README.md b/test/sageclient/README.md
index b12b2eb..60851e1 100644
--- a/test/sageclient/README.md
+++ b/test/sageclient/README.md
@@ -15,10 +15,18 @@ From any directory:
 The script:
 
 1. resolves its own directory,
-2. checks that `java` is available and is JDK 17+,
+2. uses JDK 17 or JDK 21; on macOS it auto-selects an installed 21/17 via `/usr/libexec/java_home` when the active Java is unsupported,
 3. uses the repository Gradle wrapper when present, otherwise system `gradle`,
 4. runs `gradle build` for this standalone sample.
 
+Kotlin 2.1.0 / this Gradle setup does not work with newer Java versions such as `26.0.1`. If your default `java -version` is 26, install JDK 21 or 17 and either let `build.sh` auto-detect it or export `JAVA_HOME` explicitly:
+
+```bash
+brew install --cask temurin@21
+export JAVA_HOME=$(/usr/libexec/java_home -v 21)
+./test/sageclient/build.sh
+```
+
 Extra Gradle arguments can be appended, for example:
 
 ```bash
diff --git a/test/sageclient/build.sh b/test/sageclient/build.sh
index ecd14f7..99583cd 100755
--- a/test/sageclient/build.sh
+++ b/test/sageclient/build.sh
@@ -5,20 +5,95 @@ SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_DIR="$SCRIPT_DIR"
 ROOT_DIR="$(cd -- "$SCRIPT_DIR/../.." && pwd)"
 
+java_major_version() {
+  local java_bin="$1"
+  local version_line
+  version_line="$($java_bin -version 2>&1 | head -n 1)"
+  printf '%s\n' "$version_line" | sed -E 's/.*version "([0-9]+)(\.[0-9]+)?.*/\1/'
+}
+
+is_supported_java() {
+  local java_bin="$1"
+  local major
+  major="$(java_major_version "$java_bin")"
+  [[ "$major" =~ ^[0-9]+$ ]] && [ "$major" -ge 17 ] && [ "$major" -le 21 ]
+}
+
+try_set_java_home() {
+  local candidate
+
+  if [ -n "${JAVA_HOME:-}" ] && [ -x "$JAVA_HOME/bin/java" ] && is_supported_java "$JAVA_HOME/bin/java"; then
+    return 0
+  fi
+
+  if command -v /usr/libexec/java_home >/dev/null 2>&1; then
+    for candidate in 21 17; do
+      if JAVA_HOME_CANDIDATE="$(/usr/libexec/java_home -v "$candidate" 2>/dev/null)" \
+        && [ -x "$JAVA_HOME_CANDIDATE/bin/java" ] \
+        && is_supported_java "$JAVA_HOME_CANDIDATE/bin/java"; then
+        export JAVA_HOME="$JAVA_HOME_CANDIDATE"
+        export PATH="$JAVA_HOME/bin:$PATH"
+        echo "Using JAVA_HOME=$JAVA_HOME"
+        return 0
+      fi
+    done
+  fi
+
+  for candidate in \
+    /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home \
+    /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home \
+    /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home \
+    /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home \
+    /usr/lib/jvm/java-21-openjdk \
+    /usr/lib/jvm/java-17-openjdk \
+    /usr/lib/jvm/java-21-openjdk-amd64 \
+    /usr/lib/jvm/java-17-openjdk-amd64; do
+    if [ -x "$candidate/bin/java" ] && is_supported_java "$candidate/bin/java"; then
+      export JAVA_HOME="$candidate"
+      export PATH="$JAVA_HOME/bin:$PATH"
+      echo "Using JAVA_HOME=$JAVA_HOME"
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+if ! try_set_java_home; then
+  if ! command -v java >/dev/null 2>&1; then
+    cat >&2 <<'EOF'
+ERROR: java was not found in PATH.
+Please install JDK 17 or JDK 21, then rerun this script.
+EOF
+    exit 1
+  fi
+fi
+
 if ! command -v java >/dev/null 2>&1; then
   cat >&2 <<'EOF'
 ERROR: java was not found in PATH.
-Please install JDK 17 or newer, then rerun this script.
+Please install JDK 17 or JDK 21, then rerun this script.
 EOF
   exit 1
 fi
 
 JAVA_VERSION_OUTPUT="$(java -version 2>&1 | head -n 1)"
-JAVA_VERSION="$(printf '%s\n' "$JAVA_VERSION_OUTPUT" | sed -E 's/.*version "([0-9]+)(\.[0-9]+)?.*/\1/')"
+JAVA_VERSION="$(java_major_version java)"
 if ! [[ "$JAVA_VERSION" =~ ^[0-9]+$ ]]; then
-  echo "WARNING: Unable to parse Java version from: $JAVA_VERSION_OUTPUT" >&2
-elif [ "$JAVA_VERSION" -lt 17 ]; then
-  echo "ERROR: JDK 17 or newer is required. Found: $JAVA_VERSION_OUTPUT" >&2
+  echo "ERROR: Unable to parse Java version from: $JAVA_VERSION_OUTPUT" >&2
+  exit 1
+elif [ "$JAVA_VERSION" -lt 17 ] || [ "$JAVA_VERSION" -gt 21 ]; then
+  cat >&2 <<EOF
+ERROR: This project currently requires JDK 17 or JDK 21.
+Found: $JAVA_VERSION_OUTPUT
+
+Kotlin 2.1.0 / this Gradle setup fails with newer Java versions such as 26.0.1.
+Install a supported JDK and rerun, for example on macOS:
+  brew install --cask temurin@21
+  export JAVA_HOME=\$(/usr/libexec/java_home -v 21)
+
+If JDK 17/21 is already installed, set JAVA_HOME before running build.sh.
+EOF
   exit 1
 fi