NimBLE Host Return Codes

Introduction

Summary

The NimBLE host reports status to the application via a set of return codes. The host encompasses several layers of the Bluetooth specification that each defines its own set of status codes. Rather than “abstract away” information from lower layers that the application developer might find useful, the NimBLE host aims to indicate precisely what happened when something fails. Consequently, the host utilizes a rather large set of return codes.

A return code of 0 indicates success. For failure conditions, the return codes are partitioned into five separate sets:

| Set | Condition | Notes| |-----|-------------| | Core | Errors detected internally by the NimBLE host. | | ATT | The ATT server has reported a failure via the transmission of an ATT Error Response. The return code corresponds to the value of the Error Code field in the response. | | HCI | The controller has reported an error to the host via a command complete or command status HCI event. The return code corresponds to the value of the Status field in the event. | L2CAP | An L2CAP signaling procedure has failed and an L2CAP Command Reject was sent as a result. The return code corresponds to the value of the Reason field in the command. | Security manager (us) | The host detected an error during a security manager procedure and sent a Pairing Failed command to the peer. The return code corresponds to the value of the Reason field in the Pairing Failed command. | | Security manager (peer) | A security manager procedure failed because the peer sent us a Pairing Failed command. The return code corresponds to the value of the Reason field in the Pairing Failed command. |

The return codes in the core set are defined by the NimBLE Host. The other sets are defined in the Bluetooth specification; the codes in this latter group are referred to as formal status codes. As defined in the Bluetooth specification, the formal status code sets are not disjoint. That is, they overlap. For example, the spec defines a status code of 1 to have all of the following meanings:

LayerMeaning
ATTInvalid handle.
HCIUnknown HCI command.
L2CAPSignalling MTU exceeded.
SMPasskey entry failed.

Clearly, the host can't just return an unadorned formal status code and expect the application to make sense of it. To resolve this ambiguity, the NimBLE host divides the full range of an int into several subranges. Each subrange corresponds to one of the five return code sets. For example, the ATT set is mapped onto the subrange [0x100, 0x200). To indicate an ATT error of 3 (write not permitted), the NimBLE host returns a value 0x103 to the application.

The host defines a set of convenience macros for converting from a formal status code to NimBLE host status code. These macros are documented in the table below.

MacroStatus code setBase value
BLE_HS_ATT_ERR()ATT0x100
BLE_HS_HCI_ERR()HCI0x200
BLE_HS_L2C_ERR()L2CAP0x300
BLE_HS_SM_US_ERR()Security manager (us)0x400
BLE_HS_SM_PEER_ERR()Security manager (peer)0x500

Example

The following example demonstrates how an application might determine which error is being reported by the host. In this example, the application performs the GAP encryption procedure and checks the return code. To simplify the example, the application uses a hypothetical my_blocking_enc_proc() function, which blocks until the pairing operation has completed.

void
encrypt_connection(uint16_t conn_handle)
{
    int rc;

    /* Perform a blocking GAP encryption procedure. */
    rc = my_blocking_enc_proc(conn_handle);
    switch (rc) {
    case 0:
        console_printf("success - link successfully encrypted\n");
        break;

    case BLE_HS_ENOTCONN:
        console_printf("failure - no connection with handle %d\n",
                       conn_handle);
        break;

    case BLE_HS_ERR_SM_US_BASE(BLE_SM_ERR_CONFIRM_MISMATCH):
        console_printf("failure - mismatch in peer's confirm and random "
                       "commands.\n");
        break;

    case BLE_HS_ERR_SM_PEER_BASE(BLE_SM_ERR_CONFIRM_MISMATCH):
        console_printf("failure - peer reports mismatch in our confirm and "
                       "random commands.\n");
        break;

    default:
        console_printf("failure - other error: 0x%04x\n", rc);
        break;
    }
}

Return Code Reference

Header

All NimBLE host return codes are made accessible by including the following header:

#include "host/ble_hs.h"

Return codes - Core

The precise meaning of each of these error codes depends on the function that returns it. The API reference for a particular function indicates the conditions under which each of these codes are returned.

ValueNameCondition
0x00N/ASuccess
0x01BLE_HS_EAGAINTemporary failure; try again.
0x02BLE_HS_EALREADYOperation already in progress or completed.
0x03BLE_HS_EINVALOne or more arguments are invalid.
0x04BLE_HS_EMSGSIZEThe provided buffer is too small.
0x05BLE_HS_ENOENTNo entry matching the specified criteria.
0x06BLE_HS_ENOMEMOperation failed due to resource exhaustion.
0x07BLE_HS_ENOTCONNNo open connection with the specified handle.
0x08BLE_HS_ENOTSUPOperation disabled at compile time.
0x09BLE_HS_EAPPApplication callback behaved unexpectedly.
0x0aBLE_HS_EBADDATACommand from peer is invalid.
0x0bBLE_HS_EOSMynewt OS error.
0x0cBLE_HS_ECONTROLLEREvent from controller is invalid.
0x0dBLE_HS_ETIMEOUTOperation timed out.
0x0eBLE_HS_EDONEOperation completed successfully.
0x0fBLE_HS_EBUSYOperation cannot be performed until procedure completes.
0x10BLE_HS_EREJECTPeer rejected a connection parameter update request.
0x11BLE_HS_EUNKNOWNUnexpected failure; catch all.
0x12BLE_HS_EROLEOperation requires different role (e.g., central vs. peripheral).
0x13BLE_HS_ETIMEOUT_HCIHCI request timed out; controller unresponsive.
0x14BLE_HS_ENOMEM_EVTController failed to send event due to memory exhaustion (combined host-controller only).
0x15BLE_HS_ENOADDROperation requires an identity address but none configured.
0x16BLE_HS_ENOTSYNCEDAttempt to use the host before it is synced with controller.
0x17BLE_HS_EAUTHENInsufficient authentication.
0x18BLE_HS_EAUTHORInsufficient authorization.
0x19BLE_HS_EENCRYPTInsufficient encryption level.
0x1aBLE_HS_EENCRYPT_KEY_SZInsufficient key size.
0x1bBLE_HS_ESTORE_CAPStorage at capacity.
0x1cBLE_HS_ESTORE_FAILStorage IO error.

Return codes - ATT

NimBLE ValueFormal ValueNameCondition
0x01010x01BLE_ATT_ERR_INVALID_HANDLEThe attribute handle given was not valid on this server.
0x01020x02BLE_ATT_ERR_READ_NOT_PERMITTEDThe attribute cannot be read.
0x01030x03BLE_ATT_ERR_WRITE_NOT_PERMITTEDThe attribute cannot be written.
0x01040x04BLE_ATT_ERR_INVALID_PDUThe attribute PDU was invalid.
0x01050x05BLE_ATT_ERR_INSUFFICIENT_AUTHENThe attribute requires authentication before it can be read or written.
0x01060x06BLE_ATT_ERR_REQ_NOT_SUPPORTEDAttribute server does not support the request received from the client.
0x01070x07BLE_ATT_ERR_INVALID_OFFSETOffset specified was past the end of the attribute.
0x01080x08BLE_ATT_ERR_INSUFFICIENT_AUTHORThe attribute requires authorization before it can be read or written.
0x01090x09BLE_ATT_ERR_PREPARE_QUEUE_FULLToo many prepare writes have been queued.
0x010a0x0aBLE_ATT_ERR_ATTR_NOT_FOUNDNo attribute found within the given attribute handle range.
0x010b0x0bBLE_ATT_ERR_ATTR_NOT_LONGThe attribute cannot be read or written using the Read Blob Request.
0x010c0x0cBLE_ATT_ERR_INSUFFICIENT_KEY_SZThe Encryption Key Size used for encrypting this link is insufficient.
0x010d0x0dBLE_ATT_ERR_INVALID_ATTR_VALUE_LENThe attribute value length is invalid for the operation.
0x010e0x0eBLE_ATT_ERR_UNLIKELYThe attribute request that was requested has encountered an error that was unlikely, and therefore could not be completed as requested.
0x010f0x0fBLE_ATT_ERR_INSUFFICIENT_ENCThe attribute requires encryption before it can be read or written.
0x01100x10BLE_ATT_ERR_UNSUPPORTED_GROUPThe attribute type is not a supported grouping attribute as defined by a higher layer specification.
0x01110x11BLE_ATT_ERR_INSUFFICIENT_RESInsufficient Resources to complete the request.

Return codes - HCI

NimBLE ValueFormal ValueNameCondition
0x02010x01BLE_ERR_UNKNOWN_HCI_CMDUnknown HCI Command
0x02020x02BLE_ERR_UNK_CONN_IDUnknown Connection Identifier
0x02030x03BLE_ERR_HW_FAILHardware Failure
0x02040x04BLE_ERR_PAGE_TMOPage Timeout
0x02050x05BLE_ERR_AUTH_FAILAuthentication Failure
0x02060x06BLE_ERR_PINKEY_MISSINGPIN or Key Missing
0x02070x07BLE_ERR_MEM_CAPACITYMemory Capacity Exceeded
0x02080x08BLE_ERR_CONN_SPVN_TMOConnection Timeout
0x02090x09BLE_ERR_CONN_LIMITConnection Limit Exceeded
0x020a0x0aBLE_ERR_SYNCH_CONN_LIMITSynchronous Connection Limit To A Device Exceeded
0x020b0x0bBLE_ERR_ACL_CONN_EXISTSACL Connection Already Exists
0x020c0x0cBLE_ERR_CMD_DISALLOWEDCommand Disallowed
0x020d0x0dBLE_ERR_CONN_REJ_RESOURCESConnection Rejected due to Limited Resources
0x020e0x0eBLE_ERR_CONN_REJ_SECURITYConnection Rejected Due To Security Reasons
0x020f0x0fBLE_ERR_CONN_REJ_BD_ADDRConnection Rejected due to Unacceptable BD_ADDR
0x02100x10BLE_ERR_CONN_ACCEPT_TMOConnection Accept Timeout Exceeded
0x02110x11BLE_ERR_UNSUPPORTEDUnsupported Feature or Parameter Value
0x02120x12BLE_ERR_INV_HCI_CMD_PARMSInvalid HCI Command Parameters
0x02130x13BLE_ERR_REM_USER_CONN_TERMRemote User Terminated Connection
0x02140x14BLE_ERR_RD_CONN_TERM_RESRCSRemote Device Terminated Connection due to Low Resources
0x02150x15BLE_ERR_RD_CONN_TERM_PWROFFRemote Device Terminated Connection due to Power Off
0x02160x16BLE_ERR_CONN_TERM_LOCALConnection Terminated By Local Host
0x02170x17BLE_ERR_REPEATED_ATTEMPTSRepeated Attempts
0x02180x18BLE_ERR_NO_PAIRINGPairing Not Allowed
0x02190x19BLE_ERR_UNK_LMPUnknown LMP PDU
0x021a0x1aBLE_ERR_UNSUPP_REM_FEATUREUnsupported Remote Feature / Unsupported LMP Feature
0x021b0x1bBLE_ERR_SCO_OFFSETSCO Offset Rejected
0x021c0x1cBLE_ERR_SCO_ITVLSCO Interval Rejected
0x021d0x1dBLE_ERR_SCO_AIR_MODESCO Air Mode Rejected
0x021e0x1eBLE_ERR_INV_LMP_LL_PARMInvalid LMP Parameters / Invalid LL Parameters
0x021f0x1fBLE_ERR_UNSPECIFIEDUnspecified Error
0x02200x20BLE_ERR_UNSUPP_LMP_LL_PARMUnsupported LMP Parameter Value / Unsupported LL Parameter Value
0x02210x21BLE_ERR_NO_ROLE_CHANGERole Change Not Allowed
0x02220x22BLE_ERR_LMP_LL_RSP_TMOLMP Response Timeout / LL Response Timeout
0x02230x23BLE_ERR_LMP_COLLISIONLMP Error Transaction Collision
0x02240x24BLE_ERR_LMP_PDULMP PDU Not Allowed
0x02250x25BLE_ERR_ENCRYPTION_MODEEncryption Mode Not Acceptable
0x02260x26BLE_ERR_LINK_KEY_CHANGELink Key cannot be Changed
0x02270x27BLE_ERR_UNSUPP_QOSRequested QoS Not Supported
0x02280x28BLE_ERR_INSTANT_PASSEDInstant Passed
0x02290x29BLE_ERR_UNIT_KEY_PAIRINGPairing With Unit Key Not Supported
0x022a0x2aBLE_ERR_DIFF_TRANS_COLLDifferent Transaction Collision
0x022c0x2cBLE_ERR_QOS_PARMQoS Unacceptable Parameter
0x022d0x2dBLE_ERR_QOS_REJECTEDQoS Rejected
0x022e0x2eBLE_ERR_CHAN_CLASSChannel Classification Not Supported
0x022f0x2fBLE_ERR_INSUFFICIENT_SECInsufficient Security
0x02300x30BLE_ERR_PARM_OUT_OF_RANGEParameter Out Of Mandatory Range
0x02320x32BLE_ERR_PENDING_ROLE_SWRole Switch Pending
0x02340x34BLE_ERR_RESERVED_SLOTReserved Slot Violation
0x02350x35BLE_ERR_ROLE_SW_FAILRole Switch Failed
0x02360x36BLE_ERR_INQ_RSP_TOO_BIGExtended Inquiry Response Too Large
0x02370x37BLE_ERR_SEC_SIMPLE_PAIRSecure Simple Pairing Not Supported By Host
0x02380x38BLE_ERR_HOST_BUSY_PAIRHost Busy - Pairing
0x02390x39BLE_ERR_CONN_REJ_CHANNELConnection Rejected due to No Suitable Channel Found
0x023a0x3aBLE_ERR_CTLR_BUSYController Busy
0x023b0x3bBLE_ERR_CONN_PARMSUnacceptable Connection Parameters
0x023c0x3cBLE_ERR_DIR_ADV_TMODirected Advertising Timeout
0x023d0x3dBLE_ERR_CONN_TERM_MICConnection Terminated due to MIC Failure
0x023e0x3eBLE_ERR_CONN_ESTABLISHMENTConnection Failed to be Established
0x023f0x3fBLE_ERR_MAC_CONN_FAILMAC Connection Failed
0x02400x40BLE_ERR_COARSE_CLK_ADJCoarse Clock Adjustment Rejected but Will Try to Adjust Using Clock Dragging

Return codes - L2CAP

NimBLE ValueFormal ValueNameCondition
0x03000x00BLE_L2CAP_SIG_ERR_CMD_NOT_UNDERSTOODInvalid or unsupported incoming L2CAP sig command.
0x03010x01BLE_L2CAP_SIG_ERR_MTU_EXCEEDEDIncoming packet too large.
0x03020x02BLE_L2CAP_SIG_ERR_INVALID_CIDNo channel with specified ID.

Return codes - Security manager (us)

NimBLE ValueFormal ValueNameCondition
0x04010x01BLE_SM_ERR_PASSKEYThe user input of passkey failed, for example, the user cancelled the operation.
0x04020x02BLE_SM_ERR_OOBThe OOB data is not available.
0x04030x03BLE_SM_ERR_AUTHREQThe pairing procedure cannot be performed as authentication requirements cannot be met due to IO capabilities of one or both devices.
0x04040x04BLE_SM_ERR_CONFIRM_MISMATCHThe confirm value does not match the calculated compare value.
0x04050x05BLE_SM_ERR_PAIR_NOT_SUPPPairing is not supported by the device.
0x04060x06BLE_SM_ERR_ENC_KEY_SZThe resultant encryption key size is insufficient for the security requirements of this device.
0x04070x07BLE_SM_ERR_CMD_NOT_SUPPThe SMP command received is not supported on this device.
0x04080x08BLE_SM_ERR_UNSPECIFIEDPairing failed due to an unspecified reason.
0x04090x09BLE_SM_ERR_REPEATEDPairing or authentication procedure is disallowed because too little time has elapsed since last pairing request or security request.
0x040a0x0aBLE_SM_ERR_INVALThe Invalid Parameters error code indicates that the command length is invalid or that a parameter is outside of the specified range.
0x040b0x0bBLE_SM_ERR_DHKEYIndicates to the remote device that the DHKey Check value received doesn’t match the one calculated by the local device.
0x040c0x0cBLE_SM_ERR_NUMCMPIndicates that the confirm values in the numeric comparison protocol do not match.
0x040d0x0dBLE_SM_ERR_ALREADYIndicates that the pairing over the LE transport failed due to a Pairing Request sent over the BR/EDR transport in process.
0x040e0x0eBLE_SM_ERR_CROSS_TRANSIndicates that the BR/EDR Link Key generated on the BR/EDR transport cannot be used to derive and distribute keys for the LE transport.

Return codes - Security manager (peer)

NimBLE ValueFormal ValueNameCondition
0x05010x01BLE_SM_ERR_PASSKEYThe user input of passkey failed, for example, the user cancelled the operation.
0x05020x02BLE_SM_ERR_OOBThe OOB data is not available.
0x05030x03BLE_SM_ERR_AUTHREQThe pairing procedure cannot be performed as authentication requirements cannot be met due to IO capabilities of one or both devices.
0x05040x04BLE_SM_ERR_CONFIRM_MISMATCHThe confirm value does not match the calculated compare value.
0x05050x05BLE_SM_ERR_PAIR_NOT_SUPPPairing is not supported by the device.
0x05060x06BLE_SM_ERR_ENC_KEY_SZThe resultant encryption key size is insufficient for the security requirements of this device.
0x05070x07BLE_SM_ERR_CMD_NOT_SUPPThe SMP command received is not supported on this device.
0x05080x08BLE_SM_ERR_UNSPECIFIEDPairing failed due to an unspecified reason.
0x05090x09BLE_SM_ERR_REPEATEDPairing or authentication procedure is disallowed because too little time has elapsed since last pairing request or security request.
0x050a0x0aBLE_SM_ERR_INVALThe Invalid Parameters error code indicates that the command length is invalid or that a parameter is outside of the specified range.
0x050b0x0bBLE_SM_ERR_DHKEYIndicates to the remote device that the DHKey Check value received doesn’t match the one calculated by the local device.
0x050c0x0cBLE_SM_ERR_NUMCMPIndicates that the confirm values in the numeric comparison protocol do not match.
0x050d0x0dBLE_SM_ERR_ALREADYIndicates that the pairing over the LE transport failed due to a Pairing Request sent over the BR/EDR transport in process.
0x050e0x0eBLE_SM_ERR_CROSS_TRANSIndicates that the BR/EDR Link Key generated on the BR/EDR transport cannot be used to derive and distribute keys for the LE transport.