| Issue | Primary Cause | Quick Fix |
|---|---|---|
| Service Not Found | Service UUID missing from optionalServices |
Add service UUID to request options |
| Security Error | Non-HTTPS environment | Use localhost or HTTPS |
| GATT Error | Device disconnected or out of range | Re-establish connection and check proximity |
| Flag Disabled | Browser permissions blocked | Enable Web Bluetooth in browser flags |
What is Web Bluetooth Service Not Found?
The “Service Not Found” error in Web Bluetooth occurs when the browser cannot locate a specific GATT (Generic Attribute Profile) service on a connected peripheral. This typically happens during the getPrimaryService() call in your JavaScript execution flow.
Even if a device successfully pairs, the browser security model prevents access to services that weren’t explicitly requested during the initial scan. If your script tries to interact with a UUID that wasn’t “whitelisted” in the request, the browser throws a NotFoundError.
This error is common when developers assume that pairing grants full access to all device services. In reality, Web Bluetooth requires a strict declaration of intent to maintain user privacy and device security.
Step-by-Step Solutions
1. Include UUIDs in optionalServices
The most frequent cause is forgetting to list the service UUID in the requestDevice options. Browsers will only allow access to services defined in filters or optionalServices.
navigator.bluetooth.requestDevice({
filters: [{ name: 'MyDevice' }],
optionalServices: ['battery_service', 'heart_rate'] // Must include these!
})
.then(device => device.gatt.connect())
.then(server => server.getPrimaryService('battery_service'))
.catch(error => console.error(error));2. Verify UUID Formatting
Ensure you are using the correct format for UUIDs. Web Bluetooth accepts 16-bit or 32-bit aliases for standard GATT services, but custom services require the full 128-bit string.
Always use lowercase strings for UUIDs. Mixed-case strings or missing dashes in 128-bit UUIDs can lead to the service being unrecognized by the Web Bluetooth API.
3. Enable Experimental Web Platform Features
If you are working on a desktop browser or an uncertified device, the API might be restricted. You may need to manually enable the feature set to allow the browser to communicate effectively with the GATT server.
Navigate to chrome://flags/#enable-experimental-web-platform-features in your browser. Set this to “Enabled” and restart the browser to clear any cached permission blocks.
4. Check OS-Level Bluetooth Permissions
On macOS and Windows 10/11, the browser itself must have permission to use Bluetooth. If the OS blocks the browser, the GATT discovery process will fail silently or return a “Service Not Found” error.
Go to your System Settings > Privacy & Security > Bluetooth, and ensure your browser (Chrome, Edge, or Bluefy) is toggled to “On”.
5. Handle Disconnections Gracefully
If the device drops the connection immediately after pairing, the service discovery will fail. Implement a reconnection logic or use the gattserverdisconnected event to monitor the state.
device.addEventListener('gattserverdisconnected', onDisconnected);
function onDisconnected(event) {
const device = event.target;
console.log('Device ' + device.name + ' is disconnected.');
// Attempt to reconnect here
}