error-message

📡 Live from GitHub — This documentation is fetched directly from error-message.md and cached for 6 hours.

Keywords: Error, message, debugging, exception, throw, ESLint rule, error handling, LLM-optimized

Enforce providing a message when creating built-in Error objects for better debugging

Enforce providing a message when creating built-in Error objects for better debugging. This rule is part of eslint-plugin-maintainability and provides LLM-optimized error messages with suggestions.

Quick Summary

Aspect	Details
Severity	Error (correctness)
Auto-Fix	💡 Suggests fixes
Category	Quality
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')`

Examples

❌ Incorrect

// Missing message
throw new Error();
throw new TypeError();
throw new RangeError();

// Empty string message
throw new Error('');
throw new Error('   ');

// 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: {
    'maintainability/error-message': 'error'
  }
}

Allow in Catch Blocks

{
  rules: {
    'maintainability/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

no-silent-errors - Prevents empty catch blocks
no-missing-error-context - Ensures error context

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 tracked

Mitigation: 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 tracked

Mitigation: Ensure imported values follow the same constraints. Use TypeScript for type safety.