Skip to content

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.
  • ReaderServiceException covers connection, card communication and verification failures.
  • CardCapacityException is a more specific ReaderServiceException for an oversized message. Catch it first if you want to show a separate capacity message.
  • NDefValueException, NDefEncodingException, NDefMessageException and TlvException cover 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.