# Error Codes (/integrations/nestjs/reference/error-codes)



This page catalogs the error types `@kubemq/nestjs-transport` throws and a troubleshooting table
for the most common failures. For configuration options see
[Configuration](/integrations/nestjs/reference/configuration); for the decorator and context surface see the
[API reference](/integrations/nestjs/reference/api).

## Errors [#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:

```typescript title="exception-filter.ts"
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](/integrations/nestjs/how-to/configuration-and-resilience#error-handling--exception-filters).

## Troubleshooting / FAQ [#troubleshooting--faq]

<Accordions>
  <Accordion title="Connection refused (ECONNREFUSED)">
    The broker is not reachable at the configured `address`. Verify it is running and the `host:port` is correct. Start a local broker with Docker:

    <RunKubeMQ ports="[50000, 9090]" />

    Port `50000` is the gRPC port the transport connects to. Port `9090` is the shared HTTP server (used by the REST and connector endpoints, not by this transport, which speaks native gRPC).
  </Accordion>

  <Accordion title="Decorator not firing">
    The handler class must be a NestJS-managed provider. List the `@Injectable()` handler class in a module's `providers`, and ensure that module imports `KubeMQModule`. A standalone class instantiated outside the Nest container is never wired to the transport.
  </Accordion>

  <Accordion title="Cannot find module '@kubemq/nestjs-transport/testing'">
    The `./testing` subpath resolves only against a package version whose `exports` map includes the `./testing` entry. Confirm `node_modules/@kubemq/nestjs-transport/package.json` lists `"./testing"` under `exports`, then reinstall if needed.
  </Accordion>

  <Accordion title="Cannot find module '@kubemq/nestjs-transport/cqrs'">
    The CQRS bridge needs the optional peer dependency. Install it:

    ```bash title="cqrs.sh"
    npm install @nestjs/cqrs
    ```
  </Accordion>

  <Accordion title="Serialization mismatch">
    The same `KubeMQSerializer` / `KubeMQDeserializer` pair must be configured on both the `KubeMQServer` and any `KubeMQModule.register()` client that exchange messages. When deserialization fails, a `SerializationError` is thrown.
  </Accordion>

  <Accordion title="Messages not received">
    Verify the channel name matches exactly between sender and receiver, and that the server microservice was actually started with `app.startAllMicroservices()` in your bootstrap.
  </Accordion>

  <Accordion title="Queue messages reappearing (redelivery)">
    Unacknowledged queue messages are redelivered. In manual-ack mode (`{ manualAck: true }`) you must call `ctx.ack()` after successful processing; otherwise rely on auto-ack (the default). Inspect `ctx.receiveCount` to detect repeated deliveries.
  </Accordion>

  <Accordion title="Health check failing">
    Construct the `KubeMQHealthIndicator` from the **same** `KubeMQServer` instance you pass to `connectMicroservice`, via `KubeMQHealthIndicator.fromServer(server)`. Using a different instance checks a different connection and reports a false negative.
  </Accordion>

  <Accordion title="CQRS events not distributed (ordering)">
    Confirm `KubeMQCqrsModule.forRoot()` is imported **after** both `CqrsModule` and `KubeMQModule.forRoot()`. The bridge depends on the connection configuration provided by `KubeMQModule.forRoot()`.
  </Accordion>
</Accordions>

## See Also [#see-also]

<Cards>
  <Card title="Configuration" href="/integrations/nestjs/reference/configuration" description="Connection options and every configuration interface." />

  <Card title="API reference" href="/integrations/nestjs/reference/api" description="Module methods, decorators, contexts, codecs, constants, and enums." />

  <Card title="Configuration & Resilience" href="/integrations/nestjs/how-to/configuration-and-resilience" description="DLQ routing, validation, idempotency, backpressure, and exception filters." />
</Cards>