Zowe Gateway fails to start on v2.1 after z/OSMF 2512 Maintenance

Products

• Zowe

Issue/Introduction

After applying Zowe compatibility fixes (UO03613, UO03614) for z/OSMF 2512 maintenance, Zowe servers failed to start with the following errors:

Unknown Protocol Error: java.lang.IllegalArgumentException: unknown protocol: safkeyring

ClassNotFoundException: Error: Could not find or load main class Development Caused by: java.lang.ClassNotFoundException: Development (Note: The class name in the error will match the first word of your Certificate Alias if it contains spaces.)

Environment

Zowe 2.1 (specifically v2.18.4 and earlier)

Cause

• Protocol Change: 
  
  Java 11 and 17 require the safkeyringjce:// protocol for RACF keyrings. The legacy safkeyring:// protocol is no longer supported for these Java versions
  
  
• Script Bug: 
  
  A bug in the Zowe v2.1.18.4 Gateway startup script fails to properly quote the -Dserver.internal.ssl.keyAlias variable. If the certificate alias contains spaces (e.g., "Zowe Development"), the JVM interprets the second word as the main class name, resulting in a ClassNotFoundException.

Resolution

1. Update SAF keyring protocol in zowe.yaml 
   
   From: file: safkeyring:////ZWESUSR/ZoweKeyring
   
   To: file: safkeyringjce:////ZWESUSR/ZoweKeyring

2. Patch Gateway start.sh

Until you can upgrade to a version containing the permanent fix (v2.18.5+), manually edit the gateway startup script:

1. Locate the file: /path/to/zowe/builds/components/gateway/bin/start.sh
2. Search for the keyword -Dserver.internal.ssl.keyAlias.
3. Change the unquoted line: -Dserver.internal.ssl.keyAlias=${ZWE_configs_server_internal_ssl_certificate_keystore_alias:-${key_alias}} \
4. To include double quotes: -Dserver.internal.ssl.keyAlias="${ZWE_configs_server_internal_ssl_certificate_keystore_alias:-${key_alias}}" \
5. Save the file

Note: Ensure you restart the servers after making these changes

Additional Information

These changes are required only for environments running Java 11 or Java 17.

Zowe v2.18.5, it is scheduled for release Sept. 26th 2026

SAF keyring use in JAVA 8 and JAVA 17