Want to play a game?
Stay organized with collections
Save and categorize content based on your preferences.
Challenge yourself by answering these five questions.
Question 1
The following error message is supposed to target
non-technical users:
- You entered a bad age (32.6)
If you were reviewing this error message, which replacement error
message would you recommend instead?
The specified age, 32.6, contains a decimal point.
Enter an age that doesn't contain a decimal point. For example: 32
This answer demonstrates how to correct the problem. The wording is
appropriate for the target audience.
The specified age, 32.6, is a floating-point number instead of an
integer.
The terms "floating-point number" and "integer" aren't ideal for an
audience of non-technical users, so the error message doesn't really
demonstrate how to correct the problem.
You entered an age, 32.6, that our software can't process.
This error message doesn't demonstrate how to correct the problem,
or even explain what the problem is.
Question 2
Which one of the following error messages would be best for application
programmers?
The call read_file(my_input_stream) failed because
my_input_stream does not exist.
To open a stream for reading, call the
open_file function. For example:
my_input_stream = open_file("~/.bashrc").
This error message explains the problem and the solution.
Also, the solution provides an example.
You forgot to open my_input_stream.
This error message blames the user. Also, this error message doesn't
provide a solution.
my_input_stream doesn't exist. Open
my_input_stream before calling read_file.
This error message is so concise that some helpful information
(for example, how to open an input stream) has been excluded.
Question 3
What problem do you see in the following error message:
- The file you are attempting to upload is too big (12 MB).
Please pick a smaller file and try again.
The problem statement is missing the maximum allowable
file size.
This error message should have been:
The file you are attempting to upload is too big (12 MB).
You can only upload files that are 8MB or smaller.
Please pick a smaller file and try again.
The error message doesn't provide a solution to the problem.
Actually, the error message does provide a solution.
The error message contains a double negative.
This error message doesn't contain a double negative.
Question 4
What problem do you see in the following error message:
- The specified file ('camelia.txt') does not exist.
Pick a different datastore and try again.
The first sentence and second sentence use different terms
for the same kind of object.
The first sentence uses the term *file*. The second sentence
calls the same object a *datastore*. This error message will
likely confuse some users.
The error message doesn't specify the problem.
Actually, the first sentence of the error message does specify
the problem.
The error message blames the user.
The error message doesn't blame anyone.
The error message is overly apologetic.
The error message doesn't apologize.
Question 5
Consider the following error message displayed for a consumer
appliance:
- Error: Bad checksum. Change the battery in this
device.
What error message would be more appropriate for a consumer
appliance?
The battery is starting to fail. Replace the battery as soon as
possible by following these directions: <URL of battery
replacement documentation>
This error message explains the problem in an appropriate way
for nontechnical people. A full description of how to change a
battery is probably too detailed for an error message, so
providing the URL of full documentation is wiser. (Also,
if the battery is removed, the user cannot read the directions
in an error message.)
Your device has reported a bad checksum. Change the battery in
this device.
Very few people know what "bad checksum" means, so this phrase
will just annoy and confuse most people.
The battery is starting to fail. Replace the battery as soon as
possible by following these directions:
1. Turn off the device by moving the switch from 1 to 0.
2. Unlatch the battery case located in the rear of this
device.
...
10. Turn the device back on by moving the switch from 0 to 1.
If the directions for replacing the battery were two steps instead
of ten steps, then putting battery replacement instructions inside
the error message might be okay.
However, for a ten-step process, it is probably wiser to refer
users to complete documentation that contains illustrations or
videos. (Also, if the battery is removed, the user cannot read the
directions appearing in the error message.)
The error message is fine as is.
This error message doesn't describe the problem appropriately for
the target audience. The description of the solution isn't adequate.
Next unit: Summary
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-03-31 UTC.
[null,null,["Last updated 2025-03-31 UTC."],[[["\u003cp\u003eThis content focuses on crafting effective error messages by analyzing five example scenarios and their improved alternatives.\u003c/p\u003e\n"],["\u003cp\u003eIt emphasizes the importance of clear, concise, and user-friendly language tailored to the target audience (technical or non-technical).\u003c/p\u003e\n"],["\u003cp\u003eThe examples highlight the need to provide solutions and avoid technical jargon, blame, or overly complex explanations in error messages.\u003c/p\u003e\n"],["\u003cp\u003eIt demonstrates how to provide specific and actionable information, such as maximum file sizes or links to detailed instructions, when necessary.\u003c/p\u003e\n"],["\u003cp\u003eUltimately, the goal is to help users understand and resolve errors efficiently without frustration.\u003c/p\u003e\n"]]],["This content analyzes error messages and suggests improvements. It presents five questions, each with an example error message and evaluations of alternative messages. Key actions include identifying issues like technical jargon, lack of clarity, missing information (e.g., maximum file size), inconsistent terminology, and inadequate solutions. It emphasizes tailoring messages to the target audience (non-technical vs. programmers) and providing clear, actionable instructions or links to further guidance. It also recommends avoiding user-blaming language.\n"],null,["# Want to play a game?\n\n\u003cbr /\u003e\n\nChallenge yourself by answering these five questions.\n\nQuestion 1\n----------\n\nThe following error message is supposed to target\nnon-technical users:\n\n- You entered a bad age (32.6)\n\nIf you were reviewing this error message, which replacement error\nmessage would you recommend instead? \nThe specified age, 32.6, contains a decimal point. Enter an age that doesn't contain a decimal point. For example: 32 \nThis answer demonstrates how to correct the problem. The wording is appropriate for the target audience. \nThe specified age, 32.6, is a floating-point number instead of an integer. \nThe terms \"floating-point number\" and \"integer\" aren't ideal for an audience of non-technical users, so the error message doesn't really demonstrate how to correct the problem. \nYou entered an age, 32.6, that our software can't process. \nThis error message doesn't demonstrate how to correct the problem, or even explain what the problem is.\n\nQuestion 2\n----------\n\nWhich one of the following error messages would be best for application\nprogrammers? \nThe call read_file(my_input_stream) failed because my_input_stream does not exist. To open a stream for reading, call the open_file function. For example: my_input_stream = open_file(\"\\~/.bashrc\"). \nThis error message explains the problem and the solution. Also, the solution provides an example. \nYou forgot to open my_input_stream. \nThis error message blames the user. Also, this error message doesn't provide a solution. \nmy_input_stream doesn't exist. Open my_input_stream before calling read_file. \nThis error message is so concise that some helpful information (for example, how to open an input stream) has been excluded.\n\nQuestion 3\n----------\n\nWhat problem do you see in the following error message:\n\n- The file you are attempting to upload is too big (12 MB). Please pick a smaller file and try again. \nThe problem statement is missing the maximum allowable file size. \nThis error message should have been: \n\nThe file you are attempting to upload is too big (12 MB). You can only upload files that are 8MB or smaller. Please pick a smaller file and try again. \nThe error message doesn't provide a solution to the problem. \nActually, the error message does provide a solution. \nThe error message contains a double negative. \nThis error message doesn't contain a double negative.\n\nQuestion 4\n----------\n\nWhat problem do you see in the following error message:\n\n- The specified file ('camelia.txt') does not exist. Pick a different datastore and try again. \nThe first sentence and second sentence use different terms for the same kind of object. \nThe first sentence uses the term \\*file\\*. The second sentence calls the same object a \\*datastore\\*. This error message will likely confuse some users. \nThe error message doesn't specify the problem. \nActually, the first sentence of the error message does specify the problem. \nThe error message blames the user. \nThe error message doesn't blame anyone. \nThe error message is overly apologetic. \nThe error message doesn't apologize.\n\nQuestion 5\n----------\n\nConsider the following error message displayed for a consumer\nappliance:\n\n- Error: Bad checksum. Change the battery in this device.\n\nWhat error message would be more appropriate for a consumer\nappliance? \nThe battery is starting to fail. Replace the battery as soon as possible by following these directions: \\\u003c*URL of battery\nreplacement documentation*\\\u003e \nThis error message explains the problem in an appropriate way for nontechnical people. A full description of how to change a battery is probably too detailed for an error message, so providing the URL of full documentation is wiser. (Also, if the battery is removed, the user cannot read the directions in an error message.) \nYour device has reported a bad checksum. Change the battery in this device. \nVery few people know what \"bad checksum\" means, so this phrase will just annoy and confuse most people. \nThe battery is starting to fail. Replace the battery as soon as possible by following these directions:\n\n1. Turn off the device by moving the switch from 1 to 0. \n2. Unlatch the battery case located in the rear of this device. \n... \n10. Turn the device back on by moving the switch from 0 to 1. \nIf the directions for replacing the battery were two steps instead of ten steps, then putting battery replacement instructions inside the error message might be okay. However, for a ten-step process, it is probably wiser to refer users to complete documentation that contains illustrations or videos. (Also, if the battery is removed, the user cannot read the directions appearing in the error message.) \nThe error message is fine as is. \nThis error message doesn't describe the problem appropriately for the target audience. The description of the solution isn't adequate.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n**Next unit:** [Summary](/tech-writing/error-messages/summary)"]]
