Writing Effective Error Messages

Last updated on Dec 13, 2024

Open a doc issue   |   Edit this page

Error messages play a vital role in the user experience. When written well—clear, actionable, and concise—they help users understand and resolve issues efficiently. Poorly written messages, however, can frustrate users and generate unnecessary support tickets.

This topic provides examples of correct and incorrect error messages. Following these guidelines will help you create effective error messages that serve users well, even without UX writing expertise.

Core Principles

An effective error message should follow these fundamental principles:

1. Be specific about what went wrong. Generic messages like "An error occurred" leave users guessing and frustrated. Instead, clearly identify the issue: "Unable to save file: disk space is full" tells users exactly what happened and hints at how to fix it.

2. Use human-readable language while maintaining technical accuracy. Consider this example for a database connection error:

   Correct

   Cannot connect to database: Server [db-prod-01] is not responding. Please verify the server is running.

   Incorrect

   ERR_DB_CONN_REFUSED: Exception at line 142

3. Provide actionable guidance. Users need to know what they can do to resolve the issue. For a failed login attempt:

   Correct

   Incorrect username or password. Try again or click 'Forgot Password' to reset.

   Incorrect

   Authentication failed

Message Structure

A well-structured error message contains three key components:

1. Problem Statement: What went wrong
2. Technical Context: Why it happened (when appropriate)
3. Resolution Steps: What the user can do about it

Correct

Unable to upload file [report.pdf] because it exceeds the 10MB size limit. Compress the file or split it into smaller parts and try again.

Incorrect

File error

Technical Considerations

When implementing error handling, consider these technical aspects:

Error Logging: While users see the friendly message, log detailed technical information for debugging:

try {
    await saveDocument(data);
} catch (error) {
    // Log detailed error for developers
    logger.error(`Document save failed: ${error.stack}`);

    // Return user-friendly message
    throw new UserFacingError(
        'Unable to save document. Please try again in a few minutes or contact support if the problem persists.'
    );
}

Internationalization: Design your error message system to support multiple languages from the start. Avoid concatenating strings to form error messages, as this can break when translated:

// Incorrect
return "File " + filename + " is too large";

// Correct
return formatMessage(
    'error.file.size.exceeded',
    { filename: filename, maxSize: '10MB' }
);

Security Considerations

Balance information disclosure with security.

Security-related errors

For security-related errors, be cautious about revealing too much:

Correct

Password does not meet security requirements. Please review password criteria below.

Incorrect

Invalid password: Must contain at least one uppercase letter

System-level errors

For system-level errors, avoid exposing internal details:

Correct

Unable to retrieve account information. Please try again later or contact support.

Incorrect

MySQL error: Table 'users.accounts' doesn't exist on line 247

Testing Error Messages

Incorporate error message testing into your development process:

1. Test with real users or team members who weren't involved in writing the messages
2. Verify messages in different contexts and states
3. Check how messages appear in different viewport sizes
4. Ensure error messages are accessible to screen readers

Common Patterns to Avoid

To maintain consistency and clarity, avoid these common pitfalls:

System-oriented messages

Correct

Unable to load user profile. Try refreshing the page.

Incorrect

NullReferenceException in UserController

Blame-oriented language

Correct

Enter a valid email address in the format: example@domain.com

Incorrect

You entered invalid data