Why Error Messages Matter More in the Age of AI

#ai #programming

Everyone talks about AI writing code.
Nobody talks about AI debugging code.

Bad error messages are the worst, we've all seen them. You open the logs or run your program and see something like this...

Error: something went wrong

It leaves you asking:

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

You might have written some of these pretty silly error messages, I know I have. They don't help us fix software quickly because we first have to figure out why the error happened.

Rust has been shipping fantastic error messages for years.

Take this example where I accidentally call println instead of println!.

$ cargo run                                                                                                   101 ↵
   Compiling ducksay v0.2.0 (~/oss/ducksay)
error[E0423]: expected function, found macro `print`
  --> src/main.rs:51:3
   |
51 |   print("{}", render_with_style(&message, cli.width.get(), style));
   |   ^^^^^ not a function
   |
help: use `!` to invoke the macro
   |
51 |   print!("{}", render_with_style(&message, cli.width.get(), style));
   |

It's fantastic! It tells you what went wrong, where it occurred, and how to fix it.

When you're building software, you should make your error messages exceptional (punny 😂).

Here's another example from Vite+ where I had a syntax error in the config file.

$ vp dev

failed to load config from ~/oss/test-ssr-on-aws/vite.config.ts
error when starting dev server:
Error: Build failed with 1 error:

[PARSE_ERROR] Error: Unexpected token
   ╭─[ vite.config.ts:5:3 ]
   │
 5 │   ,
   │   ┬
   │   ╰──
───╯

Now imagine debugging code with generic error messages that tell you absolutely nothing helpful. You'll have to manually trace through the code to figure out what the heck is going on.

AI agents run into the same problem. If the error tells them almost nothing, they have to spend extra time reading files, tracing execution paths, and making additional tool calls just to understand what failed.

So what can we do to help humans and AI? Here are some of my top recommendations for writing good error messages.

1. Be descriptive and specific

We started with Error: Something went wrong and it tells us almost nothing.

Instead, tell them exactly what happened and where it happened.

Error: Failed to load config.toml.

config.toml:23
Unknown property "waddles".

2. Emit structured logs

A good error message is one thing, but don't forget about the logs around it.

Using a structured logger like pino means every log includes useful metadata like timestamps, log levels, and request IDs.

If you're writing JavaScript, pair it with pino-pretty and your logs become a lot easier on the eyes too 💅.

[17:35:28.992] ERROR (1337): Loading configuration failed, unknown property "waddles" config.toml:23

Those logs aren't just useful in your terminal. Once they're in your observability platform, you can search, filter, and correlate events across your application. CloudWatch now supports OpenTelemetry, so all of that structured context comes along for the ride.

The more useful context your logs contain, the less detective work there is for both you and your AI agent.

3. Provide solutions/hints

When things go wrong (and they will), a simple hint can save someone a lot of time.

Error: Missing required environment variable "DATABASE_URL".

hint: Add DATABASE_URL to your .env file or export it before starting the application.

Not every error can tell you exactly how to fix it, and adding hints can take extra work. But if you already know the most common fix, include it anyway. It'll save someone or an AI agent a trip to the documentation.

FWIW some of these will only make sense when you are in a trusted environment. When giving errors to clients it's best to not give them more than they need, otherwise you might leak information that could help an attacker.

For trusted environments like a local CLI tool or a server application where you control the logs it's ideal to craft really detailed messages.

Good error messages have always mattered. AI agents make them even more valuable.

AI is getting better at writing code every day. We should make it just as good at debugging it.

Follow AWS for more articles like this.