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



The error reference for the **MassTransit.KubeMQ** transport: the exception hierarchy, the validation messages thrown at bus startup, and the runtime triggers behind connection, timeout, and CQ request failures. For handling patterns — retries, native DLQ, and the `_error` / `_skipped` channels — see the [Error Handling & DLQ guide](/integrations/masstransit/how-to/error-handling-dlq).

## Exception hierarchy [#exception-hierarchy]

All transport exceptions derive from `KubeMQTransportException`, which itself extends MassTransit's `MassTransitException`. The base type carries optional `Channel` and `ServerAddress` properties for diagnostics, and three subtypes classify the failure. All four live in the `MassTransit.KubeMQTransport.Exceptions` namespace.

```text
MassTransitException
└── KubeMQTransportException          (Channel, ServerAddress)
    ├── KubeMQTransportConfigurationException
    ├── KubeMQTransportConnectionException
    └── KubeMQTransportTimeoutException
```

| Exception                               | Thrown when                                                                               |
| --------------------------------------- | ----------------------------------------------------------------------------------------- |
| `KubeMQTransportException`              | Base type; general transport errors (e.g. `Queue send failed`, `Query request failed`)    |
| `KubeMQTransportConfigurationException` | Invalid configuration or an unsupported operation (e.g. delayed delivery on Events)       |
| `KubeMQTransportConnectionException`    | The connection cannot be established or is lost (`Connection closed`, gRPC `UNAVAILABLE`) |
| `KubeMQTransportTimeoutException`       | A send/publish operation exceeds its configured timeout                                   |

## Validation errors [#validation-errors]

`KubeMQTransportOptions.Validate()` runs automatically during bus startup and throws `KubeMQTransportConfigurationException` with one of these messages for an out-of-range value, so misconfiguration fails fast at boot.

| Property             | Rule                       | Message                                                             |
| -------------------- | -------------------------- | ------------------------------------------------------------------- |
| `Host`               | Non-empty / non-whitespace | `Host is invalid: must be non-empty`                                |
| `Port`               | `1`–`65535`                | `Port is invalid: {Port} must be between 1 and 65535`               |
| `PollTimeoutSeconds` | `1`–`3600`                 | `PollTimeoutSeconds is invalid: {value} must be between 1 and 3600` |
| `MaxPollMessages`    | `1`–`1024`                 | `MaxPollMessages is invalid: {value} must be between 1 and 1024`    |
| `ConnectionTimeout`  | `> TimeSpan.Zero`          | `ConnectionTimeout is invalid: must be positive`                    |
| `ReconnectTimeout`   | `> TimeSpan.Zero`          | `ReconnectTimeout is invalid: must be positive`                     |

You can run the same validation yourself before startup — useful in tests or a configuration smoke check:

```csharp title="ValidationDemo.cs"
using MassTransit.KubeMQTransport;
using MassTransit.KubeMQTransport.Exceptions;

try
{
    var options = new KubeMQTransportOptions { Port = 99999 };
    options.Validate();
}
catch (KubeMQTransportConfigurationException ex)
{
    // "Port is invalid: 99999 must be between 1 and 65535"
    Console.WriteLine(ex.Message);
}
```

## Runtime error triggers [#runtime-error-triggers]

| Exception                               | Representative triggers                                                                                                                                  |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KubeMQTransportConfigurationException` | `Delayed delivery is not supported for Events. Use Queues.` — you attempted to publish (Events or EventsStore) with a delay.                             |
| `KubeMQTransportConnectionException`    | `Connection closed` when the client connection cannot be re-established, or a gRPC `UNAVAILABLE` status from the server.                                 |
| `KubeMQTransportTimeoutException`       | A send or publish operation that exceeds the configured timeout — check network latency and `ConnectionTimeout`.                                         |
| `KubeMQTransportException` (general)    | `Queue send failed: {error}`; `Query request failed: {error}` / `Command request failed: {error}` when a CQ response comes back with `Executed = false`. |

<Callout type="warn">
  `Query request failed` and `Command request failed` mean the CQ response returned `Executed = false` — the responder ran and threw, *not* a timeout. A timeout means no response arrived at all (usually a missing responder or a CQ mode mismatch). See [Commands & Queries](/integrations/masstransit/how-to/commands-queries#error-semantics) for telling the two apart.
</Callout>

## Fault metadata [#fault-metadata]

When a message is faulted (after all retries are exhausted) and routed to `{channel}_error`, the transport stores fault metadata as KubeMQ tags. Read them on the error channel to understand what failed.

| Tag                      | Description                              |
| ------------------------ | ---------------------------------------- |
| `MT-Fault-ExceptionType` | Exception type name                      |
| `MT-Fault-Message`       | Exception message                        |
| `MT-Fault-StackTrace`    | Exception stack trace                    |
| `MT-Fault-Timestamp`     | When the fault occurred                  |
| `MT-Fault-RetryCount`    | Number of retry attempts before faulting |

## See also [#see-also]

<Cards>
  <Card title="Error Handling & DLQ" href="/integrations/masstransit/how-to/error-handling-dlq" description="Inspecting faulted/skipped messages, native DLQ, and retry patterns." />

  <Card title="Configuration" href="/integrations/masstransit/reference/configuration" description="Transport options, validation rules, and the header/tag mapping." />

  <Card title="API" href="/integrations/masstransit/reference/api" description="Registration entry points and the configurator interfaces." />
</Cards>