Troubleshooting
| Symptom | What to check |
|---|---|
| Maven cannot compile for release 25 | Run mvn -version and check that Maven is using JDK 25. Check the IDE project SDK too. |
| No readers are listed | Plug in the reader, install its PC/SC-compatible driver and check that the operating system’s smart-card service is running. |
| The reader is found but connecting fails | Place a supported NTAG215 tag on the reader before calling connect(). The call opens a connection immediately. |
| The tag is rejected for writing | Use a writable NTAG215 with a supported NDEF TLV layout. A PC/SC reader may recognise other tag types that SocialCard cannot write. |
| The message is too large | Use fewer or shorter records. Preview the TLV length and let the library check the actual tag capacity when you write. |
| A link is invalid | Include the scheme, such as https://, and percent-encode spaces as %20. |
| Write verification fails | Keep the tag on the reader through the complete write and read-back. Read the tag again to check what is stored before retrying. |
Exceptions you can handle
Section titled “Exceptions you can handle”ReaderServiceExceptioncovers connection, card communication and verification failures.CardCapacityExceptionis a more specificReaderServiceExceptionfor an oversized message. Catch it first if you want to show a separate capacity message.NDefValueException,NDefEncodingException,NDefMessageExceptionandTlvExceptioncover invalid values or unsupported encoding and layout. Use the exception message to tell the user what input or tag needs attention.
When an operation fails, use try-with-resources so the service still releases the connection. See Getting started for the complete pattern.