Refactor error handling for version not found cases across multiple installers

__tests__/distributors/base-installer.test.ts

@@ -38,7 +38,7 @@ class EmptyJavaBase extends JavaBase {
   ): Promise<JavaDownloadRelease> {
     const availableVersion = '11.0.9';
     if (!semver.satisfies(availableVersion, range)) {
-      throw new Error('Available version not found');
+      throw this.createVersionNotFoundError(range, [availableVersion]);
     }
 
     return {
@@ -530,19 +530,16 @@ describe('setupJava', () => {
         checkLatest: false
       }
     ]
-  ])(
+  ])('should throw an error for version not found for %s', async input => {
-    'should throw an error for Available version not found for %s',
+    mockJavaBase = new EmptyJavaBase(input);
-    async input => {
+    await expect(mockJavaBase.setupJava()).rejects.toThrow(
-      mockJavaBase = new EmptyJavaBase(input);
+      `Could not find satisfied version for SemVer '${input.version}'`
-      await expect(mockJavaBase.setupJava()).rejects.toThrow(
+    );
-        'Available version not found'
+    expect(spyTcFindAllVersions).toHaveBeenCalled();
-      );
+    expect(spyCoreAddPath).not.toHaveBeenCalled();
-      expect(spyTcFindAllVersions).toHaveBeenCalled();
+    expect(spyCoreExportVariable).not.toHaveBeenCalled();
-      expect(spyCoreAddPath).not.toHaveBeenCalled();
+    expect(spyCoreSetOutput).not.toHaveBeenCalled();
-      expect(spyCoreExportVariable).not.toHaveBeenCalled();
+  });
-      expect(spyCoreSetOutput).not.toHaveBeenCalled();
-    }
-  );
 });
 
 describe('normalizeVersion', () => {
@@ -570,6 +567,97 @@ describe('normalizeVersion', () => {
   });
 });
 
+describe('createVersionNotFoundError', () => {
+  it('should include all required fields in error message without available versions', () => {
+    const mockJavaBase = new EmptyJavaBase({
+      version: '17.0.5',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+
+    const error = (mockJavaBase as any).createVersionNotFoundError('17.0.5');
+
+    expect(error.message).toContain(
+      "Could not find satisfied version for SemVer '17.0.5'"
+    );
+    expect(error.message).toContain('Distribution: Empty');
+    expect(error.message).toContain('Package type: jdk');
+    expect(error.message).toContain('Architecture: x64');
+  });
+
+  it('should include available versions when provided', () => {
+    const mockJavaBase = new EmptyJavaBase({
+      version: '17.0.5',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+
+    const availableVersions = ['11.0.1', '11.0.2', '17.0.1', '17.0.2'];
+    const error = (mockJavaBase as any).createVersionNotFoundError(
+      '17.0.5',
+      availableVersions
+    );
+
+    expect(error.message).toContain(
+      "Could not find satisfied version for SemVer '17.0.5'"
+    );
+    expect(error.message).toContain('Distribution: Empty');
+    expect(error.message).toContain('Package type: jdk');
+    expect(error.message).toContain('Architecture: x64');
+    expect(error.message).toContain(
+      'Available versions: 11.0.1, 11.0.2, 17.0.1, 17.0.2'
+    );
+  });
+
+  it('should truncate available versions when there are many', () => {
+    const mockJavaBase = new EmptyJavaBase({
+      version: '17.0.5',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+
+    // Create 60 versions to test truncation
+    const availableVersions = Array.from({length: 60}, (_, i) => `11.0.${i}`);
+    const error = (mockJavaBase as any).createVersionNotFoundError(
+      '17.0.5',
+      availableVersions
+    );
+
+    expect(error.message).toContain('Available versions:');
+    expect(error.message).toContain('...');
+    expect(error.message).toContain('(showing first 50 of 60 versions');
+  });
+
+  it('should include additional context when provided', () => {
+    const mockJavaBase = new EmptyJavaBase({
+      version: '17.0.5',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+
+    const availableVersions = ['11.0.1', '11.0.2'];
+    const additionalContext = 'Platform: linux';
+    const error = (mockJavaBase as any).createVersionNotFoundError(
+      '17.0.5',
+      availableVersions,
+      additionalContext
+    );
+
+    expect(error.message).toContain(
+      "Could not find satisfied version for SemVer '17.0.5'"
+    );
+    expect(error.message).toContain('Distribution: Empty');
+    expect(error.message).toContain('Package type: jdk');
+    expect(error.message).toContain('Architecture: x64');
+    expect(error.message).toContain('Platform: linux');
+    expect(error.message).toContain('Available versions: 11.0.1, 11.0.2');
+  });
+});
+
 describe('getToolcacheVersionName', () => {
   const DummyJavaBase = JavaBase as any;
 

__tests__/distributors/dragonwell-installer.test.ts

@@ -232,7 +232,7 @@ describe('getAvailableVersions', () => {
         await expect(
           distribution['findPackageForDownload'](jdkVersion)
         ).rejects.toThrow(
-          `Couldn't find any satisfied version for the specified java-version: "${jdkVersion}" and architecture: "${arch}".`
+          `Could not find satisfied version for SemVer '${jdkVersion}'`
         );
       }
     );

__tests__/distributors/graalvm-installer.test.ts

@@ -348,11 +348,17 @@ describe('GraalVMDistribution', () => {
         } as http.HttpClientResponse;
         mockHttpClient.head.mockResolvedValue(mockResponse);
 
+        // Verify the error is thrown with the expected message
         await expect(
           (distribution as any).findPackageForDownload('17.0.99')
         ).rejects.toThrow(
-          'Could not find GraalVM for SemVer 17.0.99. Please check if this version is available at https://download.oracle.com/graalvm'
+          "Could not find satisfied version for SemVer '17.0.99'"
         );
+
+        // Verify the hint about checking the base URL is included
+        await expect(
+          (distribution as any).findPackageForDownload('17.0.99')
+        ).rejects.toThrow('https://download.oracle.com/graalvm');
       });
 
       it('should throw error for unauthorized access (401)', async () => {
@@ -496,12 +502,11 @@ describe('GraalVMDistribution', () => {
 
         await expect(
           (distribution as any).findPackageForDownload('23')
-        ).rejects.toThrow("Unable to find latest version for '23-ea'");
+        ).rejects.toThrow(
-
+          "Could not find satisfied version for SemVer '23-ea'"
-        // Verify error logging
-        expect(core.error).toHaveBeenCalledWith(
-          'Available versions: 23-ea-20240716'
         );
+
+        // Verify error logging - removed as we now use the helper method which doesn't call core.error
       });
 
       it('should throw error when no matching file for architecture in EA build', async () => {
@@ -708,11 +713,9 @@ describe('GraalVMDistribution', () => {
 
       await expect(
         (distribution as any).findEABuildDownloadUrl('23-ea')
-      ).rejects.toThrow("Unable to find latest version for '23-ea'");
+      ).rejects.toThrow("Could not find satisfied version for SemVer '23-ea'");
 
-      expect(core.error).toHaveBeenCalledWith(
+      // Verify error logging - removed as we now use the helper method which doesn't call core.error
-        'Available versions: 23-ea-20240716, 23-ea-20240709'
-      );
     });
 
     it('should throw error when no matching file for architecture', async () => {

__tests__/distributors/liberica-installer.test.ts

@@ -209,7 +209,7 @@ describe('findPackageForDownload', () => {
 
   it('should throw an error', async () => {
     await expect(distribution['findPackageForDownload']('17')).rejects.toThrow(
-      /Could not find satisfied version for semver */
+      /Could not find satisfied version for SemVer/
     );
   });
 });

__tests__/distributors/liberica-linux-installer.test.ts

@@ -209,7 +209,7 @@ describe('findPackageForDownload', () => {
 
   it('should throw an error', async () => {
     await expect(distribution['findPackageForDownload']('18')).rejects.toThrow(
-      /Could not find satisfied version for semver */
+      /Could not find satisfied version for SemVer/
     );
   });
 });

__tests__/distributors/liberica-windows-installer.test.ts

@@ -209,7 +209,7 @@ describe('findPackageForDownload', () => {
 
   it('should throw an error', async () => {
     await expect(distribution['findPackageForDownload']('18')).rejects.toThrow(
-      /Could not find satisfied version for semver */
+      /Could not find satisfied version for SemVer/
     );
   });
 });

__tests__/distributors/sapmachine-installer.test.ts

@@ -266,7 +266,7 @@ describe('getAvailableVersions', () => {
         await expect(
           distribution['findPackageForDownload'](normalizedVersion)
         ).rejects.toThrow(
-          `Couldn't find any satisfied version for the specified java-version: "${normalizedVersion}" and architecture: "${arch}".`
+          `Could not find satisfied version for SemVer '${normalizedVersion}'`
         );
       }
     );

__tests__/distributors/zulu-installer.test.ts

@@ -225,6 +225,6 @@ describe('findPackageForDownload', () => {
     distribution['getAvailableVersions'] = async () => manifestData;
     await expect(
       distribution['findPackageForDownload'](distribution['version'])
-    ).rejects.toThrow(/Could not find satisfied version for semver */);
+    ).rejects.toThrow(/Could not find satisfied version for SemVer/);
   });
 });

__tests__/distributors/zulu-linux-installer.test.ts

@@ -228,6 +228,6 @@ describe('findPackageForDownload', () => {
     distribution['getAvailableVersions'] = async () => manifestData;
     await expect(
       distribution['findPackageForDownload'](distribution['version'])
-    ).rejects.toThrow(/Could not find satisfied version for semver */);
+    ).rejects.toThrow(/Could not find satisfied version for SemVer/);
   });
 });

__tests__/distributors/zulu-windows-installer.test.ts

@@ -226,6 +226,6 @@ describe('findPackageForDownload', () => {
     distribution['getAvailableVersions'] = async () => manifestData;
     await expect(
       distribution['findPackageForDownload'](distribution['version'])
-    ).rejects.toThrow(/Could not find satisfied version for semver */);
+    ).rejects.toThrow(/Could not find satisfied version for SemVer/);
   });
 });

dist/setup/index.js

@@ -84747,13 +84747,8 @@ class AdoptDistribution extends base_installer_1.JavaBase {
             });
             const resolvedFullVersion = satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
             if (!resolvedFullVersion) {
-                const availableOptions = availableVersionsWithBinaries
+                const availableVersionStrings = availableVersionsWithBinaries.map(item => item.version);
-                    .map(item => item.version)
+                throw this.createVersionNotFoundError(version, availableVersionStrings);
-                    .join(', ');
-                const availableOptionsMessage = availableOptions
-                    ? `\nAvailable versions: ${availableOptions}`
-                    : '';
-                throw new Error(`Could not find satisfied version for SemVer '${version}'. ${availableOptionsMessage}`);
             }
             return resolvedFullVersion;
         });
@@ -85102,6 +85097,28 @@ class JavaBase {
             stable
         };
     }
+    createVersionNotFoundError(versionOrRange, availableVersions, additionalContext) {
+        const parts = [
+            `Could not find satisfied version for SemVer '${versionOrRange}'.`,
+            `Distribution: ${this.distribution}`,
+            `Package type: ${this.packageType}`,
+            `Architecture: ${this.architecture}`
+        ];
+        // Add additional context if provided (e.g., platform/OS info)
+        if (additionalContext) {
+            parts.push(additionalContext);
+        }
+        if (availableVersions && availableVersions.length > 0) {
+            const maxVersionsToShow = core.isDebug() ? availableVersions.length : 50;
+            const versionsToShow = availableVersions.slice(0, maxVersionsToShow);
+            const truncated = availableVersions.length > maxVersionsToShow;
+            parts.push(`Available versions: ${versionsToShow.join(', ')}${truncated ? '...' : ''}`);
+            if (truncated) {
+                parts.push(`(showing first ${maxVersionsToShow} of ${availableVersions.length} versions, enable debug mode to see all)`);
+            }
+        }
+        return new Error(parts.join('\n'));
+    }
     setJavaDefault(version, toolPath) {
         const majorVersion = version.split('.')[0];
         core.exportVariable('JAVA_HOME', toolPath);
@@ -85223,13 +85240,8 @@ class CorrettoDistribution extends base_installer_1.JavaBase {
             });
             const resolvedVersion = matchingVersions.length > 0 ? matchingVersions[0] : null;
             if (!resolvedVersion) {
-                const availableOptions = availableVersions
+                const availableVersionStrings = availableVersions.map(item => item.version);
-                    .map(item => item.version)
+                throw this.createVersionNotFoundError(version, availableVersionStrings);
-                    .join(', ');
-                const availableOptionsMessage = availableOptions
-                    ? `\nAvailable versions: ${availableOptions}`
-                    : '';
-                throw new Error(`Could not find satisfied version for SemVer '${version}'. ${availableOptionsMessage}`);
             }
             return resolvedVersion;
         });
@@ -85463,7 +85475,8 @@ class DragonwellDistribution extends base_installer_1.JavaBase {
                 };
             });
             if (!matchedVersions.length) {
-                throw new Error(`Couldn't find any satisfied version for the specified java-version: "${version}" and architecture: "${this.architecture}".`);
+                const availableVersionStrings = availableVersions.map(item => item.jdk_version);
+                throw this.createVersionNotFoundError(version, availableVersionStrings);
             }
             const resolvedVersion = matchedVersions[0];
             return resolvedVersion;
@@ -85732,7 +85745,10 @@ class GraalVMDistribution extends base_installer_1.JavaBase {
     handleHttpResponse(response, range) {
         const statusCode = response.message.statusCode;
         if (statusCode === http_client_1.HttpCodes.NotFound) {
-            throw new Error(`Could not find GraalVM for SemVer ${range}. Please check if this version is available at ${GRAALVM_DL_BASE}`);
+            // Create the standard error with additional hint about checking the download URL
+            const error = this.createVersionNotFoundError(range);
+            error.message += `\nPlease check if this version is available at ${GRAALVM_DL_BASE}`;
+            throw error;
         }
         if (statusCode === http_client_1.HttpCodes.Unauthorized ||
             statusCode === http_client_1.HttpCodes.Forbidden) {
@@ -85749,8 +85765,8 @@ class GraalVMDistribution extends base_installer_1.JavaBase {
             core.debug(`Found ${versions.length} EA versions`);
             const latestVersion = versions.find(v => v.latest);
             if (!latestVersion) {
-                core.error(`Available versions: ${versions.map(v => v.version).join(', ')}`);
+                const availableVersions = versions.map(v => v.version);
-                throw new Error(`Unable to find latest version for '${javaEaVersion}'`);
+                throw this.createVersionNotFoundError(javaEaVersion, availableVersions);
             }
             core.debug(`Latest version found: ${latestVersion.version}`);
             const arch = this.distributionArchitecture();
@@ -85886,13 +85902,8 @@ class JetBrainsDistribution extends base_installer_1.JavaBase {
             });
             const resolvedFullVersion = satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
             if (!resolvedFullVersion) {
-                const availableOptions = versionsRaw
+                const availableVersionStrings = versionsRaw.map(item => `${item.tag_name} (${item.semver}+${item.build})`);
-                    .map(item => `${item.tag_name} (${item.semver}+${item.build})`)
+                throw this.createVersionNotFoundError(range, availableVersionStrings);
-                    .join(', ');
-                const availableOptionsMessage = availableOptions
-                    ? `\nAvailable versions: ${availableOptions}`
-                    : '';
-                throw new Error(`Could not find satisfied version for SemVer '${range}'. ${availableOptionsMessage}`);
             }
             return resolvedFullVersion;
         });
@@ -86129,13 +86140,8 @@ class LibericaDistributions extends base_installer_1.JavaBase {
                 .filter(item => (0, util_1.isVersionSatisfies)(range, item.version))
                 .sort((a, b) => -semver_1.default.compareBuild(a.version, b.version))[0];
             if (!satisfiedVersion) {
-                const availableOptions = availableVersions
+                const availableVersionStrings = availableVersions.map(item => item.version);
-                    .map(item => item.version)
+                throw this.createVersionNotFoundError(range, availableVersionStrings);
-                    .join(', ');
-                const availableOptionsMessage = availableOptions
-                    ? `\nAvailable versions: ${availableOptions}`
-                    : '';
-                throw new Error(`Could not find satisfied version for semver ${range}. ${availableOptionsMessage}`);
             }
             return satisfiedVersion;
         });
@@ -86421,9 +86427,8 @@ class MicrosoftDistributions extends base_installer_1.JavaBase {
             }
             const foundRelease = yield tc.findFromManifest(range, true, manifest, arch);
             if (!foundRelease) {
-                throw new Error(`Could not find satisfied version for SemVer ${range}.\nAvailable versions: ${manifest
+                const availableVersionStrings = manifest.map(item => item.version);
-                    .map(item => item.version)
+                throw this.createVersionNotFoundError(range, availableVersionStrings);
-                    .join(', ')}`);
             }
             return {
                 url: foundRelease.files[0].download_url,
@@ -86586,7 +86591,7 @@ class OracleDistribution extends base_installer_1.JavaBase {
                     throw new Error(`Http request for Oracle JDK failed with status code: ${response.message.statusCode}`);
                 }
             }
-            throw new Error(`Could not find Oracle JDK for SemVer ${range}`);
+            throw this.createVersionNotFoundError(range);
         });
     }
     getPlatform(platform = process.platform) {
@@ -86678,7 +86683,8 @@ class SapMachineDistribution extends base_installer_1.JavaBase {
                 };
             });
             if (!matchedVersions.length) {
-                throw new Error(`Couldn't find any satisfied version for the specified java-version: "${version}" and architecture: "${this.architecture}".`);
+                const availableVersionStrings = availableVersions.map(item => item.version);
+                throw this.createVersionNotFoundError(version, availableVersionStrings);
             }
             const resolvedVersion = matchedVersions[0];
             return resolvedVersion;
@@ -86917,13 +86923,11 @@ class SemeruDistribution extends base_installer_1.JavaBase {
             });
             const resolvedFullVersion = satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
             if (!resolvedFullVersion) {
-                const availableOptions = availableVersionsWithBinaries
+                const availableVersionStrings = availableVersionsWithBinaries.map(item => item.version);
-                    .map(item => item.version)
+                // Include platform context to help users understand OS-specific version availability
-                    .join(', ');
+                // IBM Semeru builds are OS-specific, so platform info aids in troubleshooting
-                const availableOptionsMessage = availableOptions
+                const platformContext = `Platform: ${process.platform}`;
-                    ? `\nAvailable versions: ${availableOptions}`
+                throw this.createVersionNotFoundError(version, availableVersionStrings, platformContext);
-                    : '';
-                throw new Error(`Could not find satisfied version for SemVer version '${version}' for your current OS version for ${this.architecture} architecture ${availableOptionsMessage}`);
             }
             return resolvedFullVersion;
         });
@@ -87096,13 +87100,8 @@ class TemurinDistribution extends base_installer_1.JavaBase {
             });
             const resolvedFullVersion = satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
             if (!resolvedFullVersion) {
-                const availableOptions = availableVersionsWithBinaries
+                const availableVersionStrings = availableVersionsWithBinaries.map(item => item.version);
-                    .map(item => item.version)
+                throw this.createVersionNotFoundError(version, availableVersionStrings);
-                    .join(', ');
-                const availableOptionsMessage = availableOptions
-                    ? `\nAvailable versions: ${availableOptions}`
-                    : '';
-                throw new Error(`Could not find satisfied version for SemVer '${version}'. ${availableOptionsMessage}`);
             }
             return resolvedFullVersion;
         });
@@ -87274,13 +87273,8 @@ class ZuluDistribution extends base_installer_1.JavaBase {
             });
             const resolvedFullVersion = satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
             if (!resolvedFullVersion) {
-                const availableOptions = availableVersions
+                const availableVersionStrings = availableVersions.map(item => item.version);
-                    .map(item => item.version)
+                throw this.createVersionNotFoundError(version, availableVersionStrings);
-                    .join(', ');
-                const availableOptionsMessage = availableOptions
-                    ? `\nAvailable versions: ${availableOptions}`
-                    : '';
-                throw new Error(`Could not find satisfied version for semver ${version}. ${availableOptionsMessage}`);
             }
             return resolvedFullVersion;
         });

package-lock.json

@@ -496,7 +496,6 @@
       "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.23.3.tgz",
       "integrity": "sha512-Jg+msLuNuCJDyBvFv5+OKOUjWMZgd85bKjbICd3zWrKAo+bJ49HJufi7CQE0q0uR8NGyO6xkCACScNqyjHSZew==",
       "dev": true,
-      "peer": true,
       "dependencies": {
         "@ampproject/remapping": "^2.2.0",
         "@babel/code-frame": "^7.22.13",
@@ -1788,7 +1787,6 @@
       "integrity": "sha512-B7RIQiTsCBBmY+yW4+ILd6mF5h1FUwJsVvpqkrgpszYifetQ2Ke+Z4u6aZh0CblkUGIdR59iYVyXqqZGkZ3aBw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "8.43.0",
         "@typescript-eslint/types": "8.43.0",
@@ -2037,7 +2035,6 @@
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.11.3.tgz",
       "integrity": "sha512-Y9rRfJG5jcKOE0CLisYbojUjIrIEE7AGMzA/Sm4BslANhbS+cDMpgBdcPT91oJ7OuJ9hYJBx59RjbhxVnrF8Xg==",
       "dev": true,
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -2317,7 +2314,6 @@
           "url": "https://github.com/sponsors/ai"
         }
       ],
-      "peer": true,
       "dependencies": {
         "caniuse-lite": "^1.0.30001541",
         "electron-to-chromium": "^1.4.535",
@@ -2687,7 +2683,6 @@
       "resolved": "https://registry.npmjs.org/eslint/-/eslint-8.57.0.tgz",
       "integrity": "sha512-dZ6+mexnaTIbSBZWgou51U6OmzIhYM2VcNdtiTtI7qPNZm35Akpr0f6vtw3w1Kmn5PYo+tZVfh13WrhpS6oLqQ==",
       "dev": true,
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.6.1",
@@ -3634,7 +3629,6 @@
       "resolved": "https://registry.npmjs.org/jest/-/jest-29.7.0.tgz",
       "integrity": "sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw==",
       "dev": true,
-      "peer": true,
       "dependencies": {
         "@jest/core": "^29.7.0",
         "@jest/types": "^29.6.3",
@@ -5299,7 +5293,6 @@
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.3.3.tgz",
       "integrity": "sha512-pXWcraxM0uxAS+tN0AG/BF2TyqmHO014Z070UsJ+pFvYuRSq8KH8DmWpnbXe0pEPDHXZV3FcAbJkijJ5oNEnWw==",
       "dev": true,
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"

src/distributions/adopt/installer.ts

@@ -54,15 +54,10 @@ export class AdoptDistribution extends JavaBase {
     const resolvedFullVersion =
       satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
     if (!resolvedFullVersion) {
-      const availableOptions = availableVersionsWithBinaries
+      const availableVersionStrings = availableVersionsWithBinaries.map(
-        .map(item => item.version)
+        item => item.version
-        .join(', ');
-      const availableOptionsMessage = availableOptions
-        ? `\nAvailable versions: ${availableOptions}`
-        : '';
-      throw new Error(
-        `Could not find satisfied version for SemVer '${version}'. ${availableOptionsMessage}`
       );
+      throw this.createVersionNotFoundError(version, availableVersionStrings);
     }
 
     return resolvedFullVersion;

src/distributions/base-installer.ts

@@ -259,6 +259,42 @@ export abstract class JavaBase {
     };
   }
 
+  protected createVersionNotFoundError(
+    versionOrRange: string,
+    availableVersions?: string[],
+    additionalContext?: string
+  ): Error {
+    const parts = [
+      `Could not find satisfied version for SemVer '${versionOrRange}'.`,
+      `Distribution: ${this.distribution}`,
+      `Package type: ${this.packageType}`,
+      `Architecture: ${this.architecture}`
+    ];
+
+    // Add additional context if provided (e.g., platform/OS info)
+    if (additionalContext) {
+      parts.push(additionalContext);
+    }
+
+    if (availableVersions && availableVersions.length > 0) {
+      const maxVersionsToShow = core.isDebug() ? availableVersions.length : 50;
+      const versionsToShow = availableVersions.slice(0, maxVersionsToShow);
+      const truncated = availableVersions.length > maxVersionsToShow;
+
+      parts.push(
+        `Available versions: ${versionsToShow.join(', ')}${truncated ? '...' : ''}`
+      );
+
+      if (truncated) {
+        parts.push(
+          `(showing first ${maxVersionsToShow} of ${availableVersions.length} versions, enable debug mode to see all)`
+        );
+      }
+    }
+
+    return new Error(parts.join('\n'));
+  }
+
   protected setJavaDefault(version: string, toolPath: string) {
     const majorVersion = version.split('.')[0];
     core.exportVariable('JAVA_HOME', toolPath);

src/distributions/corretto/installer.ts

@@ -75,15 +75,10 @@ export class CorrettoDistribution extends JavaBase {
     const resolvedVersion =
       matchingVersions.length > 0 ? matchingVersions[0] : null;
     if (!resolvedVersion) {
-      const availableOptions = availableVersions
+      const availableVersionStrings = availableVersions.map(
-        .map(item => item.version)
+        item => item.version
-        .join(', ');
-      const availableOptionsMessage = availableOptions
-        ? `\nAvailable versions: ${availableOptions}`
-        : '';
-      throw new Error(
-        `Could not find satisfied version for SemVer '${version}'. ${availableOptionsMessage}`
       );
+      throw this.createVersionNotFoundError(version, availableVersionStrings);
     }
     return resolvedVersion;
   }

src/distributions/dragonwell/installer.ts

@@ -51,9 +51,10 @@ export class DragonwellDistribution extends JavaBase {
       });
 
     if (!matchedVersions.length) {
-      throw new Error(
+      const availableVersionStrings = availableVersions.map(
-        `Couldn't find any satisfied version for the specified java-version: "${version}" and architecture: "${this.architecture}".`
+        item => item.jdk_version
       );
+      throw this.createVersionNotFoundError(version, availableVersionStrings);
     }
 
     const resolvedVersion = matchedVersions[0];

src/distributions/graalvm/installer.ts

@@ -149,9 +149,10 @@ export class GraalVMDistribution extends JavaBase {
     const statusCode = response.message.statusCode;
 
     if (statusCode === HttpCodes.NotFound) {
-      throw new Error(
+      // Create the standard error with additional hint about checking the download URL
-        `Could not find GraalVM for SemVer ${range}. Please check if this version is available at ${GRAALVM_DL_BASE}`
+      const error = this.createVersionNotFoundError(range);
-      );
+      error.message += `\nPlease check if this version is available at ${GRAALVM_DL_BASE}`;
+      throw error;
     }
 
     if (
@@ -180,10 +181,8 @@ export class GraalVMDistribution extends JavaBase {
 
     const latestVersion = versions.find(v => v.latest);
     if (!latestVersion) {
-      core.error(
+      const availableVersions = versions.map(v => v.version);
-        `Available versions: ${versions.map(v => v.version).join(', ')}`
+      throw this.createVersionNotFoundError(javaEaVersion, availableVersions);
-      );
-      throw new Error(`Unable to find latest version for '${javaEaVersion}'`);
     }
 
     core.debug(`Latest version found: ${latestVersion.version}`);

src/distributions/jetbrains/installer.ts

@@ -44,15 +44,10 @@ export class JetBrainsDistribution extends JavaBase {
     const resolvedFullVersion =
       satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
     if (!resolvedFullVersion) {
-      const availableOptions = versionsRaw
+      const availableVersionStrings = versionsRaw.map(
-        .map(item => `${item.tag_name} (${item.semver}+${item.build})`)
+        item => `${item.tag_name} (${item.semver}+${item.build})`
-        .join(', ');
-      const availableOptionsMessage = availableOptions
-        ? `\nAvailable versions: ${availableOptions}`
-        : '';
-      throw new Error(
-        `Could not find satisfied version for SemVer '${range}'. ${availableOptionsMessage}`
       );
+      throw this.createVersionNotFoundError(range, availableVersionStrings);
     }
 
     return resolvedFullVersion;

src/distributions/liberica/installer.ts

@@ -69,15 +69,10 @@ export class LibericaDistributions extends JavaBase {
       .sort((a, b) => -semver.compareBuild(a.version, b.version))[0];
 
     if (!satisfiedVersion) {
-      const availableOptions = availableVersions
+      const availableVersionStrings = availableVersions.map(
-        .map(item => item.version)
+        item => item.version
-        .join(', ');
-      const availableOptionsMessage = availableOptions
-        ? `\nAvailable versions: ${availableOptions}`
-        : '';
-      throw new Error(
-        `Could not find satisfied version for semver ${range}. ${availableOptionsMessage}`
       );
+      throw this.createVersionNotFoundError(range, availableVersionStrings);
     }
 
     return satisfiedVersion;

src/distributions/microsoft/installer.ts

@@ -76,11 +76,8 @@ export class MicrosoftDistributions extends JavaBase {
     const foundRelease = await tc.findFromManifest(range, true, manifest, arch);
 
     if (!foundRelease) {
-      throw new Error(
+      const availableVersionStrings = manifest.map(item => item.version);
-        `Could not find satisfied version for SemVer ${range}.\nAvailable versions: ${manifest
+      throw this.createVersionNotFoundError(range, availableVersionStrings);
-          .map(item => item.version)
-          .join(', ')}`
-      );
     }
 
     return {

src/distributions/oracle/installer.ts

@@ -112,7 +112,7 @@ export class OracleDistribution extends JavaBase {
       }
     }
 
-    throw new Error(`Could not find Oracle JDK for SemVer ${range}`);
+    throw this.createVersionNotFoundError(range);
   }
 
   public getPlatform(platform: NodeJS.Platform = process.platform): OsVersions {

src/distributions/sapmachine/installer.ts

@@ -49,9 +49,10 @@ export class SapMachineDistribution extends JavaBase {
       });
 
     if (!matchedVersions.length) {
-      throw new Error(
+      const availableVersionStrings = availableVersions.map(
-        `Couldn't find any satisfied version for the specified java-version: "${version}" and architecture: "${this.architecture}".`
+        item => item.version
       );
+      throw this.createVersionNotFoundError(version, availableVersionStrings);
     }
 
     const resolvedVersion = matchedVersions[0];

src/distributions/semeru/installer.ts

@@ -79,14 +79,16 @@ export class SemeruDistribution extends JavaBase {
     const resolvedFullVersion =
       satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
     if (!resolvedFullVersion) {
-      const availableOptions = availableVersionsWithBinaries
+      const availableVersionStrings = availableVersionsWithBinaries.map(
-        .map(item => item.version)
+        item => item.version
-        .join(', ');
+      );
-      const availableOptionsMessage = availableOptions
+      // Include platform context to help users understand OS-specific version availability
-        ? `\nAvailable versions: ${availableOptions}`
+      // IBM Semeru builds are OS-specific, so platform info aids in troubleshooting
-        : '';
+      const platformContext = `Platform: ${process.platform}`;
-      throw new Error(
+      throw this.createVersionNotFoundError(
-        `Could not find satisfied version for SemVer version '${version}' for your current OS version for ${this.architecture} architecture ${availableOptionsMessage}`
+        version,
+        availableVersionStrings,
+        platformContext
       );
     }
 

src/distributions/temurin/installer.ts

@@ -57,15 +57,10 @@ export class TemurinDistribution extends JavaBase {
     const resolvedFullVersion =
       satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
     if (!resolvedFullVersion) {
-      const availableOptions = availableVersionsWithBinaries
+      const availableVersionStrings = availableVersionsWithBinaries.map(
-        .map(item => item.version)
+        item => item.version
-        .join(', ');
-      const availableOptionsMessage = availableOptions
-        ? `\nAvailable versions: ${availableOptions}`
-        : '';
-      throw new Error(
-        `Could not find satisfied version for SemVer '${version}'. ${availableOptionsMessage}`
       );
+      throw this.createVersionNotFoundError(version, availableVersionStrings);
     }
 
     return resolvedFullVersion;

src/distributions/zulu/installer.ts

@@ -57,15 +57,10 @@ export class ZuluDistribution extends JavaBase {
     const resolvedFullVersion =
       satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
     if (!resolvedFullVersion) {
-      const availableOptions = availableVersions
+      const availableVersionStrings = availableVersions.map(
-        .map(item => item.version)
+        item => item.version
-        .join(', ');
-      const availableOptionsMessage = availableOptions
-        ? `\nAvailable versions: ${availableOptions}`
-        : '';
-      throw new Error(
-        `Could not find satisfied version for semver ${version}. ${availableOptionsMessage}`
       );
+      throw this.createVersionNotFoundError(version, availableVersionStrings);
     }
 
     return resolvedFullVersion;