Error Message Writing — Communicating Failures to Developers

In this tutorial, you will learn about Error Message Writing. We cover key concepts, practical examples, and best practices to help you master this topic.

Error messages are documentation at the point of failure. When something goes wrong, the error message is the only documentation the developer reads. A good error message tells the developer what happened, why it happened, and how to fix it.

In this lesson, you will learn how to write error messages that developers can act on.

What You'll Learn

You will write clear, actionable error messages, structure error output consistently, and document error codes with fix instructions.

Why It Matters

Error messages are the most read form of documentation. Every error message is an opportunity to teach and build trust.

Real-World Use

DodaTech rewrote all DodaZIP error messages with actionable guidance. The average time to resolve a compression error dropped from 10 minutes to 2 minutes.

flowchart LR
  A[Error Occurs] --> B[Error Message]
  B --> C[What Happened]
  B --> D[Why It Happened]
  B --> E[How to Fix]
  E --> F[Developer Resolves]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Error Message Structure

Every error message should answer three questions: What happened? Why did it happen? How do I fix it?

State the problem clearly in the first sentence. Avoid vague messages like An error occurred.

Explain the cause in terms the developer can understand. Do not expose internal implementation details unless they help.

Provide specific, actionable steps to fix the problem. Include code examples where relevant.

# Good error message
class FileTooLargeError(Exception):
    """Raised when a file exceeds the maximum compression size."""

    def __init__(self, file_path: str, file_size: int, max_size: int):
        self.file_path = file_path
        self.file_size = file_size
        self.max_size = max_size
        message = (
            f"Cannot compress {file_path}: {file_size} bytes exceeds "
            f"the maximum of {max_size} bytes. "
            f"Split the file into chunks smaller than {max_size} bytes "
            f"and compress each chunk separately."
        )
        super().__init__(message)

Error Severity Levels

Different errors need different urgency. Use consistent terminology: error for failed operations, warning for potential issues, info for informational messages.

Errors should stop the operation and require user action. Warnings should not stop the operation but should be noticed.

Document every error code with its severity level, message, cause, and fix. Developers will search for error codes.

# Error severity documentation

# E001: FILE_NOT_FOUND (Error)
# The specified input file does not exist.
# Cause: The file path is incorrect or the file was deleted.
# Fix: Verify the file path and ensure the file exists.

# W001: LARGE_FILE (Warning)
# The file is over 1 GB. Compression may take several minutes.
# Cause: File size exceeds the warning threshold.
# Fix: No action needed. The operation will proceed.

Common Mistakes

1. Vague Error Messages

An error occurred, Something went wrong. Developers cannot diagnose the problem.

2. Technical Jargon

Error messages that expose internal code details. Surface-level errors is not helpful.

3. Blaming the User

You specified an invalid path. User-provided file path is invalid is more neutral.

4. No Fix Instructions

Telling the developer what went wrong but not how to fix it.

5. Inconsistent Format

Different error formats for different modules. Developers cannot parse errors programmatically.

6. Error Codes Without Documentation

Error codes that developers must search for. Document every error code.

7. Overly Long Messages

Error messages with too much information. Developers scan for key details.

Practice Questions

1. What three questions should every error message answer?

What happened? Why did it happen? How do I fix it?

2. What is the difference between error and warning severity?

Errors stop the operation and require user action. Warnings do not stop the operation but should be noticed.

3. Why should error messages avoid blaming the user?

Blame puts developers on the defensive. Neutral language focuses on the solution.

4. How should error codes be documented?

With severity level, message, cause, and fix instructions. Developers search for error codes.

5. Challenge: Write error messages for five common failure scenarios in a tool you use. Each message should include the error, cause, and fix instructions.

FAQ

Mini Project

Audit the error messages in a tool you use. Evaluate each against the three-question standard: what, why, fix. Rewrite three error messages that do not meet the standard.

What's Next

Next: Changelog Writing