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



The scaler translates KubeMQ errors into gRPC status codes so that KEDA can apply its `fallback`
configuration consistently. The mapping is centralized in `mapKubeMQError`. This page is the
authoritative table; the [guides](/integrations/keda/how-to/autoscale-queue-consumer) and
[gRPC RPCs](/integrations/keda/reference/grpc-rpcs) reference link here rather than repeating it.

## KubeMQ error to gRPC status [#kubemq-error-to-grpc-status]

| KubeMQ Error                               | gRPC Status           | KEDA Behavior                                          |
| ------------------------------------------ | --------------------- | ------------------------------------------------------ |
| Connection refused / transient             | `Unavailable`         | KEDA uses fallback replicas.                           |
| Authentication failure                     | `Unauthenticated`     | KEDA uses fallback replicas.                           |
| Permission denied / authorization          | `PermissionDenied`    | KEDA uses fallback replicas.                           |
| Timeout / deadline exceeded                | `DeadlineExceeded`    | KEDA uses fallback replicas.                           |
| Throttled / backpressure                   | `ResourceExhausted`   | KEDA uses fallback replicas.                           |
| Not found                                  | `NotFound`            | KEDA uses fallback replicas.                           |
| Queue not found (channel absent from list) | `OK` with `Waiting=0` | Scales the target to its minimum replicas.             |
| Missing or invalid metadata                | `InvalidArgument`     | KEDA logs the error; the scale target is not adjusted. |

The "queue not found" row is the one deliberate `OK` case: when the broker responds successfully but
the named channel is not present in the returned list, the scaler reports `Waiting=0` so the
workload scales down to its minimum — an empty queue is a legitimate signal, not a failure.

<Callout type="warn">
  **Never-fake-zero guarantee.** On any *KubeMQ failure* (connection, auth, timeout, throttling, and so
  on) the scaler always returns a gRPC error — it never returns `OK` with a fabricated `Waiting=0`.
  This is what lets KEDA distinguish "the queue is genuinely empty" from "the scaler could not reach
  KubeMQ," and apply the `fallback` strategy instead of scaling a healthy workload to zero on a
  transient outage.
</Callout>

## Applying a fallback [#applying-a-fallback]

Because every KubeMQ failure surfaces as a gRPC error (not a fake zero), a `fallback` block on the
`ScaledObject` engages on a broker outage: after `failureThreshold` consecutive scaler errors, KEDA
pins the workload to `fallback.replicas` rather than guessing.

```yaml title="scaled-object-ml-inference.yaml"
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: ml-inference-scaler
spec:
  scaleTargetRef:
    name: gpu-inference-worker
  pollingInterval: 5
  cooldownPeriod: 300
  minReplicaCount: 0
  maxReplicaCount: 20
  fallback:
    failureThreshold: 3
    replicas: 2
  triggers:
    - type: external
      metadata:
        scalerAddress: kubemq-keda-scaler.default.svc.cluster.local:9090
        kubemqAddress: kubemq.default.svc.cluster.local:50000
        queueName: inference-requests
        targetWaiting: "5"
        activationTargetWaiting: "1"
```

Here, after `3` consecutive scaler failures KEDA holds the workload at `2` replicas rather than
scaling to zero, so requests keep draining even when the broker cannot be reached. Without
`fallback`, an unreachable scaler leaves the Deployment at its current replica count.

## Related [#related]

* [gRPC RPCs](/integrations/keda/reference/grpc-rpcs) — retry behavior and the RPCs these errors surface from.
* [Scale to Zero](/integrations/keda/how-to/scale-to-zero) — why `fallback` matters most at `minReplicaCount: 0`.
* [TLS and Authentication](/integrations/keda/how-to/tls-and-auth) — the auth and permission errors and their gRPC codes.