HttpMessageNotWritableException class final

Thrown when the HTTP response body could not be written.

Overview

The HttpMessageNotWritableException signals that an HTTP response body could not be successfully serialized or written to the output stream. This exception typically occurs during response generation when attempting to convert data to the desired output format.

Example

try {
  final jsonString = jsonEncode(complexObject);
  response.write(jsonString);
} on JsonUnsupportedObjectError catch (e, stackTrace) {
  throw HttpMessageNotWritableException(
    'Failed to serialize response object',
    details: {'objectType': complexObject.runtimeType},
    originalException: e,
    originalStackTrace: stackTrace,
  );
}

Common Scenarios

• Serialization Errors - Circular references in JSON serialization
• Encoding Issues - Invalid character sequences during text encoding
• I/O Errors - Closed or interrupted output streams
• Buffer Overflows - Response exceeds buffer capacity limits

Integration Example

try {
  await response.writeObject(userData);
} on HttpMessageNotWritableException catch (e) {
  logger.error('Response serialization failed', e);
  response.reset(); // Clear any partially written content
  response.statusCode = e.statusCode;
  response.write('Unable to generate response');
}

Design Notes

• Extends HttpException for consistent HTTP error handling
• Default status code 500 Internal Server Error indicates server-side issue
• Preserves original exception and stack trace for debugging
• Includes URI context when available for request identification

Related Exceptions

• HttpMessageNotReadableException - Request body reading failures
• HttpMediaTypeException - Response content type negotiation failures

Summary

The HttpMessageNotWritableException provides structured error reporting for response body generation failures, ensuring reliable error recovery and comprehensive server-side monitoring.