LTS 2022.3

Errors and Messaging

Error messages, warning messages, and info (log) messages identify problems, suggest fixes, and ultimately improve the end user experience.

Icons for error, warning, and info messages

Implementation references

Scripting API and implementation references.

Scripting API

EditorUtility.
DisplayDialog

Native OS dialog with 2 buttons

Docs ->

HelpBox

Reference for a help box in UI Toolkit.

Docs ->

Errors · UX essentials

Essential guidance about effective ways of messaging.

See all UX essentials

Overview

There are four key expression types for messages in the Editor

Unity Editor includes these message expression types:

Errors and other types of alerts are used to communicate conditions, indicate an event, or show responses to user actions. They can be expressed with dialogs (pop-up modals), window banners,
help boxes, or console and status logs.

Messages are alerts that identify problems, suggest fixes, and provide information to the user
Most messages comes in three varieties: Error messages, warning messages, and informative messages (log messages)
Message contents are usually composed of three parts: the problem, the cause, and the solution
Message language should always be polite, precise, and constructive
For errors and warnings, provide a likely workaround solution that the user can use to fix the issue

Message types

Error messages

A critical error message displayed in a help box.

Indicates a function will not complete an action
Use errors for situations where Unity can not recover or proceed normally
Error messages in the console are themed red

Warning messages

A warning message displayed in a help box.

Indicates a function that will complete an action but may return results that are not what the user intended
Use warnings for situations where Unity can recover/proceed, but users may be unaware of the side effects
Warning messages in the console are themed yellow

Informational (log) messages

An informative message displayed in a help box.

Used for communicating non-critical information
Can provide helpful advice that is not essential to the operation
Shares similarities to Tooltips
Sometimes referred to as a log message

Message theming

Color use

Illustrations of color usage showing red text and octagon icon for an error status message, yellow text and triangle icon for a warning status message, and white text and speech bubble icon for log status message

Examples of color use for error, warning, and log messages

Feedback icon colors

Icon of a red triangle to indicate a message of warning.

Intended for icons only

The icon color palette below is intended to be used for icon colors only. Do not use these colors in brand / product design implementations.

Variable name

Variable description

Light theme

Dark theme

White

Primarily for icons that need to change color on a selected state.

#F0F0F0

Yellow

Primarily for suggesting warning states and messages.

#C99700

#FFC107

Scarlet

Primarily for suggesting error states and messages.

#B10C0C

#FF534A

Status message text colors

Variable name

Variable description

Light theme

Dark theme

Default Text

The default text color

#090909

#D2D2D2

Error Text

The text color for error messages

#5A0000

#D32222

Warning Text

The text color for warning messages

#333308

#F4BC02

Help box colors

#

Common name

Variable name

Variable description

Light theme

Dark theme

Helpbox Background

--unity-colors-helpbox-background

The background color for a helpbox control

rgba(235, 235, 235, 0.2039216)

rgba(96, 96, 96, 0.2039216)

Helpbox Border

--unity-colors-helpbox-border

The border color for a helpbox control

#A9A9A9

#232323

Helpbox Text

--unity-colors-helpbox-text

The text color for a helpbox control

#161616

#BDBDBD

Icon indicating link goes to a page with foundational content

Editor Color Palette

For more information about color use in the Editor go to Foundations > Color Palette ->

Icon use

Error, warning and info (log) message icons in dark, mono, and light themes.

Red octagonal icon with white exclamation mark inside indicating an error

Error icon: Represented by a red octagonal warning icon with an exclamation mark

Yellow triangular icon with exclamation mark inside indicating a warning

Warning icon: Represented by a yellow triangle warning icon with an exclamation mark

White speech bubble icon with exclamation mark inside indicating information or a log

Info (log) icon: Represented by a white speech bubble icon with an exclamation mark

Iconography

For more information about icon use in the Editor go to Foundations > Iconography ->

Icon Library on Figma

View The Editor Icon library. (Unity internal access only) ->

Content best practices

Content overview

Well written alert messages should be:

Human-readable

Messages should use the plainest possible language that can clearly convey the message. Avoid obscure codes, abbreviations, and technical jargon. Ideally, a beginner-level user of the feature should be able to understand the alert message.

Concise

Only include the information the user needs to understand and resolve the immediate problem.

Polite

Alert messages should not be written in a negative voice that blames users for incorrect usage but in a positive or neutral voice. Avoid phrases like "illegal command".

Problem / cause / solution

All error and warning messages relating to a specific problem should include these three key elements, in this order:

The problem

Ensure the problem is clearly identified in plain language.

The cause

Where possible include the cause of the problem so that the message not only helps correct this particular instance of a problem, but becomes a teachable moment that helps prevent future mistakes.

The solution

Recommend constructive advice on how to fix the problem.

Message content

Do recommendation illustrated by a green checkbox icon

Do include any phrasing that specifically relates to that error so users can look up that exact problem on a search engine using precise wording.

Don't recommendation illustrated by a red X icon

Don't use vague wording such as "syntax error".

Don't begin the error or warning message with “Error” or “Warning” as the color styling and associated icon makes this wording redundant.

Examples

Incorrect

Correct

Breakdown

"Cannot load textures."

"Unity cannot run the application, because it cannot load the textures. Refresh the textures and re-launch the application."

Problem: Unity cannot run the application.
‍
Cause: Because it cannot load the textures.
‍
Solution: Refresh the textures and re-launch the application.

"Warning: using safe fallback for shader "yourShaderName" as it is not compatible with the VGPR ABI requirements of one or more used instance shaders, this could cause poor performance so consider using "#pragma platform_call_register_window <n>" in the ray generation shader."

"Unity is using a safe fallback shader for "yourShaderName", because the shader in your build is not compatible with the VGPR ABI requirements of one or more of the used instance shaders. To reduce performance impact, use "#pragma platform_call_register_window <n>" in the ray generation shader instead."

Problem: Unity is using a safe fallback shader for "yourShaderName".
‍
Cause: Because the shader in your build is not compatible with the VGPR ABI requirements of one or more of the used instance shaders.
‍
Solution: To reduce performance impact, use "#pragma platform_call_register_window <n>" in the ray generation shader instead.

"You have entered an invalid file name."

"This file name is invalid. File names can only contain alphanumeric characters."

Problem: This file name is invalid.
‍
Cause: File names can only contain alphanumeric characters.
‍
Solution: Please enter an alphanumeric file name.

Expression types

Dialogs (pop up modals)

Dialogs are messages that affect the entirety of the Editor

Plastic SCM requesting user input with a two button macOS 11 dialog

Dialogs are messages that present a short-term task the user must perform to continue the operation. Users won't be able to interact with the Editor until the dialog is closed.

The Editor displays the operating system dialog by default
Dialogs are invasive and should be used sparingly
Dialogs should be reserved to be used when a response is required, such as critical messages, interruptive actions or destructive outcomes, eg. saving the project before quitting
Dialogs can have one, two, or three buttons. Dialogs with only the ok button should only be used for displaying specific user decision, or acknowledgement
Avoid complex options that require information unavailable in the dialog
Alternatively referred to as pop-up modals
Option labels should be a verb or verb phrase, to indicate the action being taken when the button is clicked
Dialogs should have an opt-out from displaying option if they might be shown repeatedly

Dialog with two and three buttons

Screen captures of dialogs displaying three buttons and two buttons.

Dialogs with three and two buttons as displayed in macOS 12.

Editor displays the native OS dialog window

Scripting API

EditorUtility.
DisplayDialog

Dialog with 2 buttons

Unity Docs ->

EditorUtility.
DisplayDialogComplex

Dialog with 3 buttons

Unity Docs ->

Dialogs with two buttons ok / cancel are displayed with EditorUtility.DisplayDialog method
Dialogs with three buttons ok / alt / cancel are displayed with EditorUtility.DisplayDialogComplex method

Do not show again

For dialog boxes that might be shown repeatedly, consider using an overload of this method that takes a DialogOptOutDecisionType

Dialog opt out on Unity manual

For more information on how to set dialog opt out option go to EditorUtility.DisplayDialogComplex ->

Button options

Dialogs can have ok, cancel and alt buttons.
The ok button is the default option, and can also be activated by pressing Enter.
The cancel button is considered the "cancel" action and should usually not perform any action besides closing the dialog.
The cancel option is not set by default. If not set, only the ok button is displayed.

Button order in dialogs

OS dialogs in macOS 12 / macOS 11 and Win 8 have different button orders.

Editor displays the native operating system dialog

Button order in dialogs is dependant on the operating system.

Note that Editor API will automatically display the operating systems default button order.

On macOS 12, button order is ok / alt / cancel
On macOS 11, button order is alt / cancel / ok
On Windows, button order is ok / alt / cancel

Window banners

Window banners are messages that affect the entirety of the active window.

UI Builder message indicates that Editor-only controls are now activated.

Window banners are used to provide brief feedback about an operation that affects the entire active window. They are used for informative purposes and are not persistent on the screen.

Window banners are rendered via the function EditorWindow.ShowNotification in the affected interface.

Window banners automatically fade-out after some time. (Default duration is 4 seconds)
Window banner size is responsive to the window size
Window banners are displayed in the lower half of the window
Avoid using window banners to describe edge cases

Message duration

Default message duration is 4 seconds
Use fadeoutWait parameter to adjust the duration the notification is displayed. Measured in seconds
Duration should be based on the length of message content

Window banners on Unity manual

For more information on window banners go to EditorWindow.ShowNotification ->

Section messages (help boxes)

Help boxes affect only a section of the affected window

Shader channels displaying a warning helpbox

Section messages (help boxes) are used to alert the user of something that happened in a specific section of an Editor window, such as a property setting.
‍
They appear as help boxes in the affected interface.

They appear below the affected area (for example a property in the Inspector window)
Help boxes shift the content below it
Avoid using Help Boxes to describe edge cases
Avoid using Help Boxes for documentation

API in

UI Toolkit

HelpBox

Reference for a help box.

Docs ->

API in

IMGUI

EditorGUI.HelpBox

Reference for a help box.

Docs ->

Console and status logs

Illustration of a console window displaying console messages

Console window logs all console messages, and status message shows the latest log

Console window displaying console logs, and an error status message

Console messages are important messages that help users with debugging the application / issue and to log important messages in the console.

Are easily understood
Are informative on what happened or caused the message to appear
Contain identifying information in the message

Debug.Log is used to log messages to the Unity Console
Debug.LogWarning is used to warning messages to the Unity Console
Debug.LogError is used to error messages to the Unity Console

Console logs

Console window uses toolbar toggles to hide / show different message types for easier tracking / resolving
Time stamps are added automatically / on time the message is first logged
You can format messages with string concatenation Debug.Log("Text: " + myText.text);
You can also use Rich Text markup
Call stack information should be given in the message for easier debugging

Status messages

Latest console message is displayed in the bottom of the editor in a single line as a status message, and when clicked it opens the Console window

Assigning an object

Use context parameter to set the object which the message applies to.

If you pass a GameObject or Component as the optional context argument, the object will highlight in the Hierarchy window when you click the log message in the Console.

Debug.Log on Unity manual

For more information on how to assign objects to console messages go to Debug.Log ->

Which type to use

1. Dialog Modals 2. Window Banners 3. Help Boxes 4. Console Logs

Scale and location

If the message prevents the user from continuing until a choice or an action is made, use dialogs
If the message is a confirmation or an acknowledgment that requires minimal user interaction, use a window banner
If the message is about a property or a control in the window, use a help box
If the message is operational to the Editor, it should be logged as a console log

Severity: Is it critical? Does it disrupt the user flow?

If the message presents a short-term task the user must perform to continue the operation, use dialogs
If the message is not critical, use an info (log) message type
If the message is critical, use error or warning messages types based on the severity of the issue

Layout

When working in high-density layouts, do not disrupt the vertical layout of the interface
Help boxes are displayed after its related controls / layout
Help boxes shift the content below it
Use window banners to give informative messages about the active window

Persistence

If the message relates to a task that the user needs to perform, use a dialog
If the message needs to appear to inform the user of a non-disruptive event or give brief feedback, use window banners that disappear overtime
If the message needs to stay visible until it is resolved, and relates to a specific section or control, use a help box
Persistent messages need to be logged in the console if they affect larger operations

Log-in required.

You are trying to access the internal Editor Foundations design system.Sign-in with your Unity Google account to continue, or visit the public site.

Errors and Messaging

Implementation references

Scripting API and implementation references.

Scripting API

Errors · UX essentials

Essential guidance about effective ways of messaging.

Overview

Message types

Error messages

Warning messages

Informational (log) messages

Message theming

Color use

Feedback icon colors

Status message text colors

Help box colors

Icon use

Content best practices

Content overview

Human-readable

Concise

Polite

Problem / cause / solution

The problem

The cause

The solution

Message content

Examples

Expression types

Dialogs (pop up modals)

Dialog with two and three buttons

Scripting API

Button order in dialogs

Window banners

Section messages (help boxes)

API in

API in

Console and status logs

Which type to use

Resources

Kits, tools, libraries, and documentation to guide users through creating for the Editor.

Unity Docs

Figma UI Toolkit

You are trying to access the internal Editor Foundations design system.
Sign-in with your Unity Google account to continue, or visit the public site.