# MQRC 2017: No connection handle available

Source: https://wndsoftware.com/mainframe-errors/mqrc-2017

### MQRC 2017: No connection handle available

MQRC 2017 means the task has reached its IBM MQ open-handle limit. Check missing closes, distribution lists and subscriptions before raising limits.


#### Other names for this code

Also written as `RC2017`, `reason code 2017`, `MQ error 2017`, `MQRC_HANDLE_NOT_AVAILABLE`, `07E1`, `0x07E1`.


### What it means

MQOPEN, MQPUT1 or MQSUB needs a handle that is not available within the task limit. This differs from reaching a limit on connections. One connection can hold many object handles, so a connection count alone does not explain the failure.

IBM notes that distribution-list destinations consume handles individually. MQSUB can allocate two handles when the caller does not provide an object handle. MaxHandles is the queue-manager attribute to examine alongside application lifecycle behavior.


#### A troubleshooting example

A worker handles hundreds of messages successfully before every later MQOPEN returns 2017. Restarting the worker clears the symptom temporarily. Add a counter for completed opens and closes, then run repeated successful and deliberately failed requests. If the difference grows after each failure, fix that cleanup path. After the change, a long test should show a stable outstanding count. Merely increasing MaxHandles would postpone the same failure and make the leak harder to notice.


### Common causes

- A loop opens queues or subscriptions without closing resources that are no longer needed.
- An exception path bypasses cleanup after a partially successful initialization.
- A distribution list or subscription workload legitimately needs more handles than the task allowance.


### How to find the problem

- Record the failing call and whether the error occurs immediately or only after many requests. Gradual exhaustion suggests a lifecycle problem.
- Read the queue manager MaxHandles setting and compare it with the maximum simultaneous objects the task intentionally holds.
- Instrument opens, subscriptions and closes per task. Count outstanding resources after a request finishes, including failed requests.
- Review subscription and distribution-list usage. Counting one API call as one handle can underestimate these cases.


### How to fix it

- Close objects promptly when their useful lifetime ends. Ensure both normal and exceptional control flow release resources.
- Reuse a suitable handle across repeated operations when its ownership and lifetime are clear. Do not close another thread or component's borrowed handle.
- Increase the allowance only after establishing a legitimate peak requirement. Record the expected handle count and verify it remains bounded during a sustained test.


### What it looks like


```text
Illustrative diagnostic notes; not an IBM message template.
Worker request 1: open succeeds
Worker request 500: MQOPEN Reason=2017
Measure outstanding opens minus closes per task.
```


### IBM documentation

[IBM MQ 9.4: 2017 MQRC_HANDLE_NOT_AVAILABLE](https://www.ibm.com/docs/en/ibm-mq/9.4.x?topic=codes-2017-07e1-rc2017-mqrc-handle-not-available). Use the documentation for your installed release.

[Report a correction to WND Software](https://wndsoftware.com/contact#message).

Technical reviewer: [Albert Joseph](https://wndsoftware.com/authors/albert-joseph), WND Software.

Updated 2026-10-23. IBM documentation checked for this article. Written in our own words. For the full reference, check IBM’s MQ documentation for your version.


### Related codes

[MQRC 2025 MQRC_MAX_CONNS_LIMIT_REACHED Read →](https://wndsoftware.com/mainframe-errors/mqrc-2025)
[MQRC 2019 MQRC_HOBJ_ERROR Read →](https://wndsoftware.com/mainframe-errors/mqrc-2019)
[MQRC 2042 MQRC_OBJECT_IN_USE Read →](https://wndsoftware.com/mainframe-errors/mqrc-2042)

### Questions


#### Is MQRC 2017 the same as 2025?

No. 2017 concerns object handles for the task; 2025 concerns concurrent connections.


#### Will restarting the program fix it?

It can release resources and temporarily restore service, but a handle leak will recur unless the resource lifecycle is corrected.

[IBM MQ reason codes](https://wndsoftware.com/mainframe-errors/mq-reason-codes) · [MQRC 2016](https://wndsoftware.com/mainframe-errors/mqrc-2016) · [MQRC 2018](https://wndsoftware.com/mainframe-errors/mqrc-2018)

[← All error codes](https://wndsoftware.com/mainframe-errors/)