Improved usability of error messages in Zowe CLI
{Core} To help consumers better understand Zowe CLI error messages, Open Mainframe Project’s Zowe CLI Squad is changing the format of many of the CLI’s error messages. That new format will be used in the V3 version of Zowe CLI. However, you do not have to wait until V3 is released. This article presents the features of the new error format, describes how you can select the new format in V2, and suggests why you should (or should not) use the new format in V2.
What do the error messages look like today?
The best way to understand why we are changing the error format is to look at an example of a Zowe CLI command that fails with an error message.
The first piece of information that the consumer receives is “Command Error”. Does that imply that there is an error in the Zowe command itself? If so, I better contact the CLI team and make them fix their error. The second piece of information is “z/OSMF REST API Error”. Does that imply that there is an error in the z/OSMF API used by this command? If so, I better contact IBM and make them fix their REST API.
Of course, neither of those implications are true. By just looking at the name of the data set specified in this command, we know that the real problem is that the requested data set does not exist. The problem may not always be so glaringly obvious, but still be a simple mistake by the consumer. The format of the error message can mislead a consumer into believing that something more fundamental is wrong.
The “Error details” at the end of the message contains programmatic details. That information resembles of the kind of data output by an exception, which is NOT what occurred. Again, the response from Zowe CLI may be misleading the consumer.
If you look closely, you will notice that the following statement is shown in the middle of all of the displayed text:
- ISRZ002 Data set not cataloged — ‘DATASET.DOES.NOT.EXIST’ was not found in catalog.
That error message (which came from z/OS) does actually tell us what the real problem was. However, to borrow a phrase from the newspaper industry, we buried the lead.
What have we done to improve our messaging?
Much of the raw information contained in our error messages is useful for debugging a non-obvious problem. Our approach is to reformat the message to draw the consumer’s attention to that information which is most relevant, understandable, and actionable by the consumer. We then categorize the additional details to help put those details into the right context. The following example shows how the exact same command error will be displayed in Zowe V3.
In the new format, we first display the information that is most relevant to the consumer, and highlight that information in red. Our intention is to draw consumers’ attention to something that they can correct. We identify that our second set of information contains the response from the mainframe service. If the service’s message is not completely clear, other details in the service’s response (like return code and reason code) may enable consumers to track down more specific information about the service’s error response. Finally, in a section that we label “Diagnostic Information”, we display the details of the request that Zowe CLI sent to the service. This can help consumers identify if they inadvertently specified incorrect information in their Zowe client configuration (like a wrong port number).
Admittedly the content remains largely the same. Our objective is to focus the consumer on the most important part of the message and categorize the remaining information that is displayed.
How to select this new error format in Zowe V2
Software that supports the new error format may already be installed at your site. The ability to display error messages in the new format is available in Zowe CLI version 2.11
The Zowe CLI team avoids making breaking changes until a major new version is delivered (like Zowe version V3). The best practice for consumer automation that wants to process command output is to specify the option named --response-format-json, and then access the specific data items in the JSON document that is displayed. That is more reliable than simply matching text from standard output. In the case of these error messages, the text is not even displayed on standard output. It is displayed on standard error. Even though consumer automation that queries the text of standard error is even further removed from a best practice, it is possible that some consumer automation might be taking exactly that action.
To avoid any possibility of introducing a breaking change, consumers using Zowe V2 must explicitly choose to have errors displayed in the new format. This is easily done by setting an environment variable named ZOWE_V3_ERR_FORMAT to true. You can permanently set this environment variable in the Windows “Environment Variables” dialog or in your Linux .bashrc or .profile files. This is the best way to set it and forget about it.
If instead, you want to try out the new error format on a temporary basis, you can set the environment variable in a terminal window.
Windows Command terminal — set ZOWE_V3_ERR_FORMAT=true
Windows PowerShell terminal — $env:ZOWE_V3_ERR_FORMAT = ”true”
Linux Bash terminal — export ZOWE_V3_ERR_FORMAT=true
Looking forward
In V3, this new error format will be the only error format used by Zowe CLI. In V3, the CLI will no longer even look for the environment variable.
If you have no automation that reads the text of error messages, I recommend that you permanently set ZOWE_V3_ERR_FORMAT to true and enjoy the new format.
If the new format will break some of your existing automation, take no action and your automation will continue to work in V2 as it did previously. However, when your site installs Zowe V3, you will have to modify your automation to work with the new V3 error format. While you are still running Zowe V2, you can set ZOWE_V3_ERR_FORMAT to true on one of your test systems and take advantage of the opportunity to alter your automation on your own schedule, long before the first pre-release of V3 is delivered. After you make such modifications, your automation will already be compatible when V3 arrives.
Additional before-and-after examples
Because these format changes were made in a part of Zowe CLI that affects errors returned from many different REST requests, you will see the new format used for many different error messages. The following before-and-after screen shots provide additional examples of the new V3 error format.
You supplied incorrect credentials
Your remote service is not listening on the port that you specified
Your config does not have a basePath that is required by APIML
You asked for the spool files of a non-existent job ID
Finding out more
If you enjoyed this blog check out more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #zowe-cli or #zowe-onboarding. If this is your first time using the Open Mainframe Slack Channel register here.
Zowe is owned and managed by the Open Mainframe Project which is a Linux Foundation project.
