Android BLE Connection Problems: 7 Mistakes and Fixes

Short answer: most Android Bluetooth Low Energy (BLE) connection failures come from seven causes: missing Android 12+ permissions, scanning without filters, treating GATT status 133 as fatal, running several GATT operations at once, forgetting to write the CCCD descriptor for notifications, assuming a large MTU, and not calling gatt.close(). Fix those in order and most “BLE won’t connect” bugs disappear.

This guide walks through each mistake with the fix in Kotlin. It assumes you already know basic Android development. If you use Hilt or MVVM, the last section shows where the BLE code belongs.

1. Missing Bluetooth permissions on Android 12+

From Android 12 (API 31) BLE uses two runtime permissions, BLUETOOTH_SCAN and BLUETOOTH_CONNECT. On Android 11 and lower, scanning needs a location permission instead. If you only declare the old ones, scans return nothing and connectGatt can throw a SecurityException.

<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
    android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

Request the right set at runtime depending on Build.VERSION.SDK_INT. Use neverForLocation only if your app really does not derive location from scan results.

2. Scanning without filters

An unfiltered scan is slow, drains battery, and Android throttles apps that start and stop scans too often. Filter by service UUID (or device name/address) and use a suitable scan mode.

val filter = ScanFilter.Builder()
    .setServiceUuid(ParcelUuid(MY_SERVICE_UUID))
    .build()
val settings = ScanSettings.Builder()
    .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
    .build()
scanner.startScan(listOf(filter), settings, scanCallback)

Stop the scan as soon as you find your device, and before you call connectGatt.

3. Treating GATT status 133 as fatal

Status 133 (GATT_ERROR) is a generic failure. It shows up for timeouts, stale connection state, and device quirks. The practical fix is to close the failed GATT object and retry after a short delay, with a limit.

override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
    if (status != BluetoothGatt.GATT_SUCCESS) {
        gatt.close()
        if (retries++ < 3) scheduleReconnect(delayMs = 1000L * retries)
        return
    }
    if (newState == BluetoothProfile.STATE_CONNECTED) {
        gatt.discoverServices()
    } else if (newState == BluetoothProfile.STATE_DISCONNECTED) {
        gatt.close()
    }
}

Call discoverServices() only after you are connected, and do not start a new connection while another attempt is still in flight.

4. Running more than one GATT operation at a time

Android’s GATT client handles one operation at a time: a read, write, or descriptor write must finish (its callback fires) before you start the next. If you fire two back to back, the second is silently dropped or returns false. Put operations in a queue and run the next one from each callback.

class GattQueue {
    private val queue = ArrayDeque<() -> Boolean>()
    private var busy = false

    fun add(op: () -> Boolean) { queue.add(op); next() }
    fun done() { busy = false; next() }

    private fun next() {
        if (busy) return
        val op = queue.removeFirstOrNull() ?: return
        busy = true
        if (!op()) { busy = false; next() }
    }
}

Call done() from onCharacteristicRead, onCharacteristicWrite, and onDescriptorWrite.

5. Notifications that never arrive (the CCCD descriptor)

Calling setCharacteristicNotification(characteristic, true) only enables notifications locally. You must also write ENABLE_NOTIFICATION_VALUE to the Client Characteristic Configuration Descriptor (CCCD, UUID 00002902-0000-1000-8000-00805f9b34fb) so the device starts sending.

gatt.setCharacteristicNotification(characteristic, true)
val cccd = characteristic.getDescriptor(
    UUID.fromString("00002902-0000-1000-8000-00805f9b34fb"))
// Android 13+ (API 33)
gatt.writeDescriptor(cccd, BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE)

On Android 12 and lower, set cccd.value and call the older writeDescriptor(cccd). Use ENABLE_INDICATION_VALUE if the characteristic supports indications instead.

6. Assuming a large MTU

The default ATT MTU is 23 bytes, which leaves 20 bytes of payload per write or notification. Sending more than that without negotiating gets truncated or rejected. Request a bigger MTU after connecting and wait for onMtuChanged before sending large data.

gatt.requestMtu(247)   // call after connect, before large transfers

override fun onMtuChanged(gatt: BluetoothGatt, mtu: Int, status: Int) {
    maxPayload = mtu - 3   // 3 bytes ATT header
}

The peripheral decides what it supports, so always use the MTU you are given, not the one you asked for. Otherwise chunk your data into 20-byte pieces.

7. Not closing GATT and having no reconnect strategy

disconnect() does not free the client. Call close() when you are done or after a failed connection. Leaked GATT objects use up limited client slots and cause later connections to fail with status 133 or never complete.

  • Always call gatt.close() in the disconnected callback.
  • Reconnect with a capped retry and growing delay, not a tight loop.
  • Use autoConnect = false for a fast, direct first connection; use true only for background reconnection to a known device.
  • On Android 13+ (API 33), override the new onCharacteristicChanged(gatt, characteristic, value) callback. The older version that reads characteristic.value is deprecated.

Where to put BLE code in your app

Keep GATT handling in a single class (a repository or manager) that exposes a StateFlow of connection state and a Flow of incoming data. Inject it with Hilt and collect it from a ViewModel so rotation or navigation never leaks a connection. See our guides on Dagger Hilt, MVVM architecture and Room database for the surrounding structure.

BLE troubleshooting checklist

  1. Declared and requested the right permissions for the device’s Android version.
  2. Scan uses a filter and stops before connecting.
  3. Failed connections call close() and retry a limited number of times.
  4. All reads and writes go through a one-at-a-time queue.
  5. CCCD descriptor written for every notification you need.
  6. MTU negotiated and chunking in place.
  7. Every disconnect ends with gatt.close().

FAQ

What does Android BLE status 133 mean?

It is a generic GATT error. Common triggers are connection timeouts, a previous GATT object that was never closed, or starting operations too quickly. Close the GATT object and retry after a delay.

Why can’t my app find BLE devices on Android 12 or newer?

Usually BLUETOOTH_SCAN was not granted at runtime, or the device is not advertising the service UUID you filter on.

Why don’t I receive BLE notifications?

You must write the CCCD descriptor in addition to calling setCharacteristicNotification, and wait for onDescriptorWrite before the next operation.

What is the maximum BLE data size per write?

With the default MTU of 23, 20 bytes. After a successful MTU negotiation it is the negotiated MTU minus 3 bytes.

Should I use autoConnect true or false?

Use false for a quick direct connection while the user is waiting. Use true for background reconnection to a device you already know.

Behaviour varies by phone maker and BLE chip, so test on real devices from more than one manufacturer. Check the official Android BLE documentation for the latest API details.