brunoborges · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026
@@ -89,7 +89,7 @@ For more details,  see the full release notes on the [releases page](https://git
 
   - `gpg-passphrase-env-var`: Environment variable name for the GPG private key passphrase. Default is GPG\_PASSPHRASE.
 
-  - `mvn-toolchain-id`: Name of Maven Toolchain ID if the default name of `${distribution}_${java-version}` is not wanted.
+  - `mvn-toolchain-id`: Name of Maven Toolchain ID if the default name of `${distribution}_${java-version}` is not wanted. When supplied, the number of IDs must match the number of Java versions.
 
   - `mvn-toolchain-vendor`: Name of Maven Toolchain Vendor if the default name of `${distribution}` is not wanted.
 

@@ -1007,3 +1007,67 @@ describe('toolchains tests', () => {
     expect((contents.match(/<toolchain>/g) || []).length).toBe(runs.length);
   }, 100000);
 });
+
+describe('validateToolchainIds', () => {
+  it.each([
+    {
+      name: 'uses generated IDs when no custom IDs are supplied',
+      versions: ['17', '21'],
+      versionFile: '',
+      toolchainIds: []
+    },
+    {
+      name: 'accepts one custom ID for a single Java version',
+      versions: ['21'],
+      versionFile: '',
+      toolchainIds: ['custom-21']
+    },
+    {
+      name: 'accepts one custom ID per Java version',
+      versions: ['17', '21'],
+      versionFile: '',
+      toolchainIds: ['custom-17', 'custom-21']
+    },
+    {
+      name: 'accepts one custom ID with java-version-file',
+      versions: [],
+      versionFile: '.java-version',
+      toolchainIds: ['custom-file-version']
+    }
+  ])('$name', ({versions, versionFile, toolchainIds}) => {
+    expect(() =>
+      toolchains.validateToolchainIds(versions, versionFile, toolchainIds)
+    ).not.toThrow();
+  });
+
+  it.each([
+    {
+      name: 'rejects fewer IDs than Java versions',
+      versions: ['17', '21'],
+      versionFile: '',
+      toolchainIds: ['custom-17'],
+      expectedMessage:
+        'The number of Maven toolchain IDs (1) must match the number of Java versions (2)'
+    },
+    {
+      name: 'rejects extra IDs for a single Java version',
+      versions: ['21'],
+      versionFile: '',
+      toolchainIds: ['custom-21', 'custom-extra'],
+      expectedMessage:
+        'The number of Maven toolchain IDs (2) must match the number of Java versions (1)'
+    },
+    {
+      name: 'rejects extra IDs with java-version-file',
+      versions: [],
+      versionFile: '.java-version',
+      toolchainIds: ['custom-file-version', 'custom-extra'],
+      expectedMessage:
+        'The number of Maven toolchain IDs (2) must match the number of Java versions (1)'
+    }
+  ])('$name', ({versions, versionFile, toolchainIds, expectedMessage}) => {
+    expect(() =>
+      toolchains.validateToolchainIds(versions, versionFile, toolchainIds)
+    ).toThrow(expectedMessage);
+  });
+});
@@ -96,7 +96,7 @@ inputs:
     required: false
     default: ${{ github.server_url == 'https://github.com' && github.token || '' }}
   mvn-toolchain-id:
-    description: 'Name of Maven Toolchain ID if the default name of "${distribution}_${java-version}" is not wanted. See examples of supported syntax in Advanced Usage file'
+    description: 'Name of Maven Toolchain ID if the default name of "${distribution}_${java-version}" is not wanted. When supplied, the number of IDs must match the number of Java versions. See examples of supported syntax in Advanced Usage file'
     required: false
   mvn-toolchain-vendor:
     description: 'Name of Maven Toolchain Vendor if the default name of "${distribution}" is not wanted. See examples of supported syntax in Advanced Usage file'

@@ -128876,6 +128876,15 @@ async function write(directory, settings, overwriteSettings) {
 
 
 
+function validateToolchainIds(versions, versionFile, toolchainIds) {
+    if (!toolchainIds.length) {
+        return;
+    }
+    const versionCount = versions.length || (versionFile ? 1 : 0);
+    if (versionCount !== toolchainIds.length) {
+        throw new Error(`The number of Maven toolchain IDs (${toolchainIds.length}) must match the number of Java versions (${versionCount})`);
+    }
+}
 async function configureToolchains(version, distributionName, jdkHome, toolchainId) {
     const vendor = getInput(INPUT_MVN_TOOLCHAIN_VENDOR) || distributionName;
     const id = toolchainId || `${vendor}_${version}`;
@@ -132202,14 +132211,12 @@ async function run() {
         const setDefault = util_getBooleanInput(INPUT_SET_DEFAULT, true);
         const verifySignature = util_getBooleanInput(INPUT_VERIFY_SIGNATURE, false);
         const verifySignaturePublicKey = getInput(INPUT_VERIFY_SIGNATURE_PUBLIC_KEY) || undefined;
-        let toolchainIds = getMultilineInput(INPUT_MVN_TOOLCHAIN_ID);
+        const toolchainIds = getMultilineInput(INPUT_MVN_TOOLCHAIN_ID);
         startGroup('Installed distributions');
-        if (versions.length !== toolchainIds.length) {
-            toolchainIds = [];
-        }
         if (!versions.length && !versionFile) {
             throw new Error('java-version or java-version-file input expected');
         }
+        validateToolchainIds(versions, versionFile, toolchainIds);
         if (!versions.length) {
             core_debug('java-version input is empty, looking for java-version-file input');
             const content = external_fs_default().readFileSync(versionFile).toString().trim();

@@ -980,7 +980,7 @@ steps:
   - run: java --version
 ```
 
-In case you install multiple versions of Java at once you can use the same syntax as used in `java-versions`. Please note that you have to declare an ID for all Java versions that will be installed or the `mvn-toolchain-id` instruction will be skipped wholesale due to mapping ambiguities.
+In case you install multiple versions of Java at once you can use the same syntax as used in `java-versions`. You must declare exactly one ID for every Java version that will be installed. The action fails before installing a JDK when the number of `mvn-toolchain-id` entries does not match the number of `java-version` entries.
 
 ```yaml
 steps:

@@ -40,18 +40,18 @@ async function run() {
     );
     const verifySignaturePublicKey =
       core.getInput(constants.INPUT_VERIFY_SIGNATURE_PUBLIC_KEY) || undefined;
-    let toolchainIds = core.getMultilineInput(constants.INPUT_MVN_TOOLCHAIN_ID);
+    const toolchainIds = core.getMultilineInput(
+      constants.INPUT_MVN_TOOLCHAIN_ID
+    );
 
     core.startGroup('Installed distributions');
 
-    if (versions.length !== toolchainIds.length) {
-      toolchainIds = [];
-    }
-
     if (!versions.length && !versionFile) {
       throw new Error('java-version or java-version-file input expected');
     }
 
+    toolchains.validateToolchainIds(versions, versionFile, toolchainIds);
+
     if (!versions.length) {
       core.debug(
         'java-version input is empty, looking for java-version-file input'

@@ -14,6 +14,23 @@ interface JdkInfo {
   jdkHome: string;
 }
 
+export function validateToolchainIds(
+  versions: string[],
+  versionFile: string,
+  toolchainIds: string[]
+) {
+  if (!toolchainIds.length) {
+    return;
+  }
+
+  const versionCount = versions.length || (versionFile ? 1 : 0);
+  if (versionCount !== toolchainIds.length) {
+    throw new Error(
+      `The number of Maven toolchain IDs (${toolchainIds.length}) must match the number of Java versions (${versionCount})`
+    );
+  }
+}
+
 export async function configureToolchains(
   version: string,
   distributionName: string,
-Original file line number
+Diff line change
@@ Expand Up / @@ -980,7 +980,7 @@ steps: @@
       - run: java --version
     ```
-    In case you install multiple versions of Java at once you can use the same syntax as used in `java-versions`. Please note that you have to declare an ID for all Java versions that will be installed or the `mvn-toolchain-id` instruction will be skipped wholesale due to mapping ambiguities.
+    In case you install multiple versions of Java at once you can use the same syntax as used in `java-versions`. You must declare exactly one ID for every Java version that will be installed. The action fails before installing a JDK when the number of `mvn-toolchain-id` entries does not match the number of `java-version` entries.
     ```yaml
     steps:
@@ Expand Down @@