Troubleshooting

Introduction

Web NFC is a powerful but sometimes tricky API. If you're running into issues, this guide covers some of the most common problems and how to solve them.

1. Error: "Web NFC is not supported by this browser."

This is the most common starting issue. For Web NFC to work, you must meet all of the following conditions:

• Browser: You must be using Chrome on Android, version 89 or newer. It is not supported on iOS, desktop browsers, or other mobile browsers.
• Device: Your Android phone must have NFC hardware. Most modern mid-to-high-end phones do, but some budget models may not.
• Secure Context (HTTPS): Your website must be served over HTTPS. The API will not work on `http://` sites or local files.

2. Scanning or Writing Doesn't Start

If you click a button and nothing happens, check the following:

• User Gesture: Web NFC actions like `scan()` or `write()` must be triggered by a direct user action, like a click. You cannot start a scan automatically on page load.
• NFC is Disabled on Phone: Go to your Android settings (usually in 'Connected devices' or by pulling down the notification shade) and ensure that NFC is turned on.
• Console Errors: Check the developer console in Chrome for any specific error messages that could give you a clue.

3. Nothing Happens When Tapping the Tag

You've started a scan, the browser prompt is showing, but tapping the tag does nothing. Try these steps:

• Find the Sweet Spot: The NFC antenna's location varies on every phone. It's usually on the back, near the top or center. Move the tag slowly around the back of your phone to find the spot where it gets detected.
• Remove Phone Case: Thick or metallic phone cases can block the NFC signal. Try removing your case and scanning again.
• Tag Type: Ensure you are using a standard, NDEF-formatted NFC tag. Some proprietary tags or access cards may not be compatible with Web NFC.

4. Error: "Tag is not writable" or "Tag is read-only"

This error is straightforward. The NFC tag you are trying to write to has been permanently locked. Once a tag is made read-only, this action is irreversible. You will need a new, writable tag.

5. Error: "GATT operation failed for unknown reason."

This is a generic error that can sometimes occur. It often means there was a temporary glitch in the communication between the phone and the tag. The best solution is often to simply try the operation again.