error-message
Enforce providing a message when creating built-in Error objects for better debugging. This rule is part of eslint-plugin-reliability and provides LLM-optim
Enforce providing a message when creating built-in Error objects for better debugging. This rule is part of eslint-plugin-reliability and provides LLM-optimized error messages with suggestions.
Quick Summary
| Aspect | Details |
|---|---|
| Severity | Error (correctness) |
| Auto-Fix | 💡 Suggests fixes |
| Category | Error Handling |
| ESLint MCP | ✅ Optimized for ESLint MCP integration |
| Best For | All projects, especially debugging-heavy development |
Rule Details
Why This Matters
| Issue | Impact | Solution |
|---|---|---|
| 🐛 Debugging | No context in stack traces | Add descriptive messages |
| 📊 Error Tracking | Vague errors in monitoring | Clear error descriptions |
| 🔍 Root Cause Analysis | Hard to identify issues | Actionable messages |
| 📝 Documentation | Code intent unclear | Self-documenting errors |
Configuration
| Option | Type | Default | Description |
|---|---|---|---|
allowEmptyCatch | boolean | false | Allow empty errors in catch blocks |
Covered Error Constructors
| Constructor | Example |
|---|---|
Error | new Error('message') |
TypeError | new TypeError('message') |
ReferenceError | new ReferenceError('message') |
SyntaxError | new SyntaxError('message') |
RangeError | new RangeError('message') |
EvalError | new EvalError('message') |
URIError | new URIError('message') |
What counts as a missing message
The constructor must be the built-in one — decided by binding, so a local class
named Error is not it, and globalThis.Error is. The message is missing when
the code proves it empty: no argument, undefined, a literal that is not a
string (null, 42), or a string literal or template with nothing but
whitespace in it. A variable, a call or a template with a substitution may
carry a message and is not reported.
Examples
❌ Incorrect
// Missing message
throw new Error();
throw new TypeError();
throw new RangeError();
// Empty string message
throw new Error('');
throw new Error(' ');
throw new Error(``);
throw new Error(undefined);
// Function call without new (also caught)
throw Error();✅ Correct
// Descriptive messages
throw new Error('User not found in database');
throw new TypeError('Expected string, received number');
throw new RangeError('Value must be between 0 and 100');
// Dynamic messages
throw new Error(`Failed to process item ${id}`);
throw new Error(errorMessage);
// Template literals
throw new Error(`Invalid configuration: ${JSON.stringify(config)}`);Configuration Examples
Basic Usage
{
rules: {
'reliability/error-message': 'error'
}
}Allow in Catch Blocks
{
rules: {
'reliability/error-message': ['error', {
allowEmptyCatch: true
}]
}
}Best Practices
Good Error Messages
// ✅ Specific and actionable
throw new Error('Database connection failed: connection string missing');
throw new TypeError('Expected array of users, received undefined');
throw new RangeError('Page number must be positive integer, got -5');
// ✅ Include relevant context
throw new Error(`Failed to fetch user ${userId}: ${response.status}`);
throw new Error(`Invalid email format: ${email}`);
// ✅ Suggest solution
throw new Error('API key not found. Set OPENAI_API_KEY environment variable.');Bad Error Messages
// ❌ Too vague
throw new Error('Something went wrong');
throw new Error('Error');
throw new Error('Invalid input');
// ❌ No message at all
throw new Error();
// ❌ Generic
throw new TypeError('Type error');Error Context Pattern
// ✅ Good: Include operation context
function fetchUser(id: string) {
const user = db.find(id);
if (!user) {
throw new Error(`User not found with id: ${id}`);
}
return user;
}
// ✅ Good: Include validation context
function validateAge(age: number) {
if (age < 0 || age > 150) {
throw new RangeError(`Age must be between 0 and 150, received: ${age}`);
}
}
// ✅ Good: Include expected vs actual
function processConfig(config: unknown) {
if (typeof config !== 'object') {
throw new TypeError(
`Expected config to be an object, received ${typeof config}`
);
}
}When Not To Use
| Scenario | Recommendation |
|---|---|
| 🔄 Re-throwing errors | Use allowEmptyCatch: true |
| 🧪 Test assertions | Test frameworks handle this |
| 📦 Error wrapping | Ensure wrapper adds message |
Comparison with Alternatives
| Feature | error-message | unicorn rule | Manual review |
|---|---|---|---|
| All Error types | ✅ Yes | ✅ Yes | ⚠️ Manual |
| Function calls | ✅ Error() | ✅ Yes | ⚠️ Manual |
| Empty string check | ✅ Yes | ✅ Yes | ❌ No |
| LLM-Optimized | ✅ Yes | ❌ No | ❌ No |
| ESLint MCP | ✅ Optimized | ❌ No | ❌ No |
Related Rules
no-silent-errors- Prevents empty catch blocksno-missing-error-context- Ensures error context
Further Reading
- Error - MDN - JavaScript Error reference
- unicorn error-message - Unicorn implementation
- Error Handling Best Practices - Node.js error handling
- ESLint MCP Setup - Enable AI assistant integration
Known False Negatives
The following patterns are not detected due to static analysis limitations:
Dynamic Variable References
Why: Static analysis cannot trace values stored in variables or passed through function parameters.
// ❌ NOT DETECTED - Value from variable
const value = externalSource();
processValue(value); // Variable origin not trackedMitigation: Implement runtime validation and review code manually. Consider using TypeScript branded types for validated inputs.
Imported Values
Why: When values come from imports, the rule cannot analyze their origin or construction.
// ❌ NOT DETECTED - Value from import
import { getValue } from './helpers';
processValue(getValue()); // Cross-file not trackedMitigation: Ensure imported values follow the same constraints. Use TypeScript for type safety.
Use this rule
npm install -D oxlint-plugin-reliability{ "jsPlugins": ["oxlint-plugin-reliability"], "rules": { "reliability/error-message": "error" }}import { defineConfig } from 'vite-plus';export default defineConfig({ lint: { jsPlugins: ['oxlint-plugin-reliability'], rules: { 'reliability/error-message': 'error', }, },});oxlint-plugin-reliability re-exports eslint-plugin-reliability/oxlint: the same rules under the same IDs, and no ESLint install. Why oxlint.
Did this rule catch something? Star the repo to get new CWE coverage as we ship it — or follow the AI-code-security benchmarks behind these rules.