Stay organized with collections
Save and categorize content based on your preferences.
A few simple techniques help error messages stand out from the
surrounding text and code.
Link to more detailed documentation
When an error requires a lengthy explanation (for example, multiple sentences)
and appropriate documentation is available, use links to redirect users to
more detailed documentation.
Not recommended
Post contains unsafe information.
Recommended
Post contains unsafe information. Learn more about safety
at <link to documentation>.
Use progressive disclosure
Some error messages are long, requiring a lot of text to explain the problem
and solution. Unfortunately, users sometimes ignore long error messages,
intimidated by the "wall of text." A good compromise is to display a briefer
version of the error message and then give users the option to click something
to get the full context.
Not recommended
TextField widgets require a Material widget ancestor, but none were located.
In material design, most widgets are conceptually “printed” on a sheet of
material. To introduce a Material widget, either directly include one or use
a widget that contains a material itself.
Recommended
TextField widgets require a Material widget ancestor, but none were located.
...(Click to see more.)
In material design, most widgets are conceptually "printed" on a
sheet of material. To introduce a Material widget, either directly include
one or use a widget that contains a material itself.
Place error messages close to the error
For coding errors, place error messages as close as possible to the place
where the error occurred.
Not recommended
1: program figure_1;
2: Grade = integer;
3: var
4. print("Hello")
Use ':' instead of '=' when declaring a variable.
Recommended
1: program figure_1;
2: Grade = integer;
---------^ Syntax Error
Use ':' instead of '=' when declaring a variable.
3: var
4. print("Hello")
Handle font colors carefully
A surprising percentage of readers are color blind, so be careful with
colors in error messages. For example, the following error message will
mystify some readers:
Not recommended
The argument expects only digits. Therefore, the supplied value is
only partially correct:
3728LJ947
Many forms of color blindness exist, so just avoiding a red/green
combination isn't sufficient. Because you can't depend on all your
users being comfortable with color, we recommend pairing color with
another visual cue. For example, the following error message pairs
color with boldface:
Recommended
The argument expects only digits. Therefore, the highlighted part of the
supplied value is incorrect:
3728LJ947
The following example pairs color with extra spaces:
Recommended
The argument expects only digits. Therefore, the highlighted part of the
supplied value is incorrect:
3728 LJ 947
Alternatively, you could skip color completely:
Recommended
The argument expects only digits. Therefore, the highlighted characters
in the supplied value are incorrect:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-03-31 UTC."],[[["\u003cp\u003eError messages should be easy to find and understand, using techniques like clear placement, progressive disclosure, and links to more detailed documentation.\u003c/p\u003e\n"],["\u003cp\u003eAvoid relying solely on color to highlight errors, as it can be problematic for colorblind users; instead, pair color with other visual cues like boldface, extra spaces, or underlining.\u003c/p\u003e\n"],["\u003cp\u003eFor coding errors, place the error message as close as possible to the error in the code itself for better clarity and understanding.\u003c/p\u003e\n"],["\u003cp\u003eWhen an error needs further explanation, provide a link to relevant documentation instead of overwhelming users with lengthy text within the error message itself.\u003c/p\u003e\n"]]],["Error messages should be prominent, using techniques like links to detailed documentation for lengthy explanations. Employ progressive disclosure to shorten initial messages, offering an option for full context. Position error messages near the error's location in code. Be cautious with colors, as color blindness is common; use additional cues like bolding or spacing, or avoid color altogether to enhance accessibility.\n"],null,["# Format error messages to enhance readability\n\n\u003cbr /\u003e\n\nA few simple techniques help error messages stand out from the\nsurrounding text and code.\n\n### Link to more detailed documentation\n\nWhen an error requires a lengthy explanation (for example, multiple sentences)\nand appropriate documentation is available, use links to redirect users to\nmore detailed documentation.\n\nNot recommended\n\u003e Post contains unsafe information.\n\nRecommended\n\u003e Post contains unsafe information. Learn more about safety at \\\u003clink to documentation\\\u003e.\n\n### Use progressive disclosure\n\nSome error messages are long, requiring a lot of text to explain the problem\nand solution. Unfortunately, users sometimes ignore long error messages,\nintimidated by the \"wall of text.\" A good compromise is to display a briefer\nversion of the error message and then give users the option to click something\nto get the full context.\n\nNot recommended\n\u003e TextField widgets require a Material widget ancestor, but none were located. In material design, most widgets are conceptually \"printed\" on a sheet of material. To introduce a Material widget, either directly include one or use a widget that contains a material itself.\n\nRecommended\n\u003e TextField widgets require a Material widget ancestor, but none were located. \n\u003e **...** (Click to see more.) \n\u003e\n\u003e In material design, most widgets are conceptually \"printed\" on a sheet of material. To introduce a Material widget, either directly include one or use a widget that contains a material itself.\n\n### Place error messages close to the error\n\nFor coding errors, place error messages as close as possible to the place\nwhere the error occurred.\n\nNot recommended\n\u003e\n\u003e ```\n\u003e 1: program figure_1;\n\u003e 2: Grade = integer;\n\u003e 3: var\n\u003e 4. print(\"Hello\")\n\u003e Use ':' instead of '=' when declaring a variable.\n\u003e ```\n\nRecommended\n\u003e\n\u003e ```\n\u003e 1: program figure_1;\n\u003e 2: Grade = integer; \n\u003e ---------^ Syntax Error\n\u003e Use ':' instead of '=' when declaring a variable.\n\u003e 3: var\n\u003e 4. print(\"Hello\")\n\u003e ```\n\n### Handle font colors carefully\n\nA surprising percentage of readers are color blind, so be careful with\ncolors in error messages. For example, the following error message will\nmystify some readers:\n\nNot recommended\n\u003e The argument expects only digits. Therefore, the supplied value is only partially correct: 3728LJ947\n\nMany forms of color blindness exist, so just avoiding a red/green\ncombination isn't sufficient. Because you can't depend on all your\nusers being comfortable with color, we recommend pairing color with\nanother visual cue. For example, the following error message pairs\ncolor with boldface:\n\nRecommended\n\u003e The argument expects only digits. Therefore, the highlighted part of the supplied value is incorrect: 3728**LJ**947\n\nThe following example pairs color with extra spaces:\n\nRecommended\n\u003e The argument expects only digits. Therefore, the highlighted part of the supplied value is incorrect: 3728 LJ 947\n\nAlternatively, you could skip color completely:\n\nRecommended\n\u003e The argument expects only digits. Therefore, the highlighted characters in the supplied value are incorrect: \n\u003e\n\u003e ```\n\u003e 3728LJ947\n\u003e ^^\n\u003e ```\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n**Next unit:** [Set the right tone](/tech-writing/error-messages/set-tone)"]]
