Error Codes
The exported error types of @kubemq/nestjs-transport, the KubeMQRpcException shape, and a troubleshooting / FAQ table.
This page catalogs the error types @kubemq/nestjs-transport throws and a troubleshooting table
for the most common failures. For configuration options see
Configuration; for the decorator and context surface see the
API reference.
Errors
KubeMQRpcException extends the NestJS RpcException and carries a structured KubeMQRpcError. Two mapper helpers convert raw kubemq-js errors into it. The package also exports a set of advanced operational errors.
| Export | Description |
|---|---|
KubeMQRpcException | RpcException subclass carrying a KubeMQRpcError |
KubeMQRpcError | Interface: { statusCode, message, kubemqCode, kubemqCategory, channel? } |
mapErrorToRpcException(error) | Maps a kubemq-js error to KubeMQRpcException |
mapToRpcException(error) | Maps any error to KubeMQRpcException |
SerializationError | Thrown when serialization or deserialization fails |
ConnectionNotReadyError | Re-exported from kubemq-js; thrown when operating on an unready connection |
CircuitBreakerOpenError | Thrown when the client circuit breaker is open and rejects a call |
BackpressureOverflowError | Thrown when the internal concurrency FIFO exceeds maxQueueDepth |
DeadLetterError | Thrown when a message is routed to its dead-letter channel after retries |
MessageValidationError | Thrown when a validate DTO fails class-validator checks |
DuplicateMessageError | Thrown when idempotency dedup detects a repeated message |
The KubeMQRpcError carried by every KubeMQRpcException has a stable shape; catch the exception
and read its structured fields in an exception filter:
import { Catch, ArgumentsHost } from '@nestjs/common';
import { BaseRpcExceptionFilter } from '@nestjs/microservices';
import { KubeMQRpcException } from '@kubemq/nestjs-transport';
import type { KubeMQRpcError } from '@kubemq/nestjs-transport';
@Catch(KubeMQRpcException)
export class KubeMQExceptionFilter extends BaseRpcExceptionFilter {
catch(exception: KubeMQRpcException, host: ArgumentsHost) {
const error = exception.getError() as KubeMQRpcError;
console.error(`[${error.kubemqCategory}] ${error.kubemqCode}: ${error.message}`);
return super.catch(exception, host);
}
}For mapper behavior and verbose-error handling, see Configuration & Resilience → Error handling.
Troubleshooting / FAQ
See Also
Was this page helpful?
KubeMQCqrsOptions
Full field reference for KubeMQCqrsModule.forRoot() options that route NestJS CQRS commands, queries, and events through KubeMQ.
Spring Boot
Integrate KubeMQ into Spring Boot and Spring Cloud Stream applications with auto-configuration, a messaging template, and annotation-driven listeners.