Skip to content

Troubleshooting

Common Issues

SystemDependencyError: Missing required system dependencies

Problem: When initializing ThaiIDCardReader, you get an error about missing system dependencies.

Solution: Install the required system packages:

sudo apt-get update
sudo apt-get install -y pcscd libpcsclite-dev python3-dev swig

sudo dnf install -y pcsc-lite pcsc-lite-devel python3-devel swig

sudo pacman -S pcsclite swig python

Workaround: If dependencies are installed via other means: 

reader = ThaiIDCardReader(skip_system_check=True)

NoReaderFoundError: No smart card reader found

Problem: The library cannot detect any smartcard readers.

Symptoms: 

NoReaderFoundError: No smart card reader found. Please connect a reader.

Solutions:

  1. Check reader is connected: 

    lsusb  # Should show your USB smartcard reader

  2. Verify PC/SC daemon is running: 

    sudo systemctl status pcscd

If not running: 

sudo systemctl start pcscd
sudo systemctl enable pcscd  # Auto-start on boot

  1. Test reader detection: 
    pcsc_scan

You should see your reader listed. Press Ctrl+C to exit.

  1. Check permissions: 
    sudo usermod -a -G scard $USER
    Then log out and log back in.

NoCardDetectedError: No card detected

Problem: Reader is detected but no card is found.

Symptoms: 

NoCardDetectedError: No card detected. Please insert a Thai ID card.

Solutions:

  1. Ensure card is properly inserted:
  2. Card should be fully inserted
  3. Gold chip should be facing up and inserted first

  4. Try removing and reinserting the card

  5. Verify card is detected: 

    pcsc_scan
    When you insert a card, you should see ATR information displayed.

  6. Check for card damage:

  7. Clean the chip with a soft cloth
  8. Try a different card if available
  9. Test the card in another reader

InvalidCardError: Not a valid Thai ID card

Problem: A card is detected but it's not recognized as a Thai ID card.

Symptoms: 

InvalidCardError: The card is not a valid Thai National ID card.

Solutions:

  1. Verify it's a Thai ID card:
  2. Should be a Thai National ID card issued by the Thai government

  3. Older cards may not work (try a newer card)

  4. Check card type:

  5. Some cards may require different applet selection
  6. Contact card issuer if the card should work but doesn't

CardConnectionError: Failed to connect

Problem: Cannot establish connection to the card.

Possible causes:

  1. Card in use by another process: 

    # Kill any processes using the card
sudo systemctl restart pcscd

  2. Reader malfunction:

  3. Disconnect and reconnect the reader
  4. Try a different USB port

  5. Test with a different reader

  6. Driver issues:

  7. Install proprietary drivers if needed
  8. Check reader manufacturer website

ImportError: No module named 'smartcard'

Problem: pyscard is not installed or failed to install.

Symptoms: 

ImportError: No module named 'smartcard'

Solutions:

  1. Install system dependencies first: 

    sudo apt-get install pcscd libpcsclite-dev python3-dev swig

  2. Reinstall pyscard: 

    pip uninstall pyscard
pip install pyscard --no-cache-dir

  3. If using uv: 

    uv sync --reinstall-package pyscard

"No such file or directory: winscard.h"

Problem: Compilation error when installing pyscard.

Solution: Install libpcsclite-dev: 

sudo apt-get install libpcsclite-dev

Then reinstall: 

pip install pyscard --force-reinstall --no-cache-dir

Permission denied when accessing reader

Problem: User doesn't have permission to access the smartcard reader.

Symptoms: 

CardConnectionError: Permission denied

Solutions:

  1. Add user to scard group: 

    sudo usermod -a -G scard $USER
    Then log out and log back in.

  2. Check udev rules: 

    # List udev rules for PCSC
ls -l /usr/lib/udev/rules.d/*pcsc*

  3. Run with sudo (temporary): 

    sudo python your_script.py
    ⚠️ Not recommended for production!

Photo reading fails or is corrupted

Problem: Photo data is incomplete or invalid.

Solutions:

  1. Retry reading: 

    reader = ThaiIDCardReader(retry_count=5)
card = reader.read_card(include_photo=True)

  2. Clean card chip:

  3. Use a soft, dry cloth

  4. Avoid using liquids

  5. Check card condition:

  6. Damaged cards may have corrupted photo data

  7. Try a different card

  8. Verify photo data: 

    if card.photo and len(card.photo) > 1000:
    card.save_photo()
else:
    print("Photo data seems invalid")

Slow performance

Problem: Reading cards takes too long.

Solutions:

  1. Skip photo reading if not needed: 

    card = reader.read_card(include_photo=False)
    This reduces read time from ~3s to <1s.

  2. Use specific reader index: 

    reader = ThaiIDCardReader(reader_index=0)
    Avoids auto-detection overhead.

  3. Reuse reader instance: 

    reader = ThaiIDCardReader()
reader.connect()

# Read multiple cards
for _ in range(10):
    card = reader.read_card()
    # Process card...

reader.disconnect()

  4. Check USB connection:

  5. Use USB 2.0/3.0 ports (not USB hubs)
  6. Avoid using extension cables

TypeError: 'NoneType' object is not iterable

Problem: Trying to iterate over None value.

Common cause: Forgetting to check if photo exists:

# Wrong
photo_path = card.save_photo()

# Correct
if card.photo:
    photo_path = card.save_photo()
else:
    print("No photo data")

Encoding issues with Thai text

Problem: Thai characters display as garbage or question marks.

Solutions:

  1. Ensure UTF-8 encoding: 

    # When writing to file
with open("output.txt", "w", encoding="utf-8") as f:
    f.write(card.thai_fullname)

  2. Check terminal encoding: 

    export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

  3. Use proper font:

  4. Ensure your terminal/editor supports Thai characters
  5. Install Thai fonts if needed

CID validation fails

Problem: CID appears valid but fails validation.

Debugging: 

from pythaiidcard import validate_cid, format_cid

cid = "1234567890123"
print(f"CID: {format_cid(cid)}")
print(f"Valid: {validate_cid(cid)}")

# Manual checksum calculation
digits = [int(d) for d in cid[:12]]
check_digit = int(cid[12])
checksum = sum((13-i) * d for i, d in enumerate(digits, 1)) % 11
expected = (11 - checksum) % 10
print(f"Expected: {expected}, Got: {check_digit}")

Getting Help

If you're still experiencing issues:

  1. Check the logs: 

    import logging
logging.basicConfig(level=logging.DEBUG)

  2. Enable verbose mode (CLI): 

    pythaiidcard read --verbose

  3. Use the debug interface: 

    uv run streamlit run debug/app.py
    See real-time logs and connection status.

  4. Search existing issues:

  5. GitHub Issues

  6. Create a new issue:

  7. Include Python version, OS, reader model
  8. Provide error messages and logs
  9. Describe steps to reproduce

Platform-Specific Notes

Ubuntu 22.04+

Works out of the box with standard installation.

Ubuntu 20.04

May need to update pcscd: 

sudo apt-get update
sudo apt-get upgrade pcscd

Raspberry Pi

  1. Install dependencies as usual
  2. May need to add user to dialout group: 
    sudo usermod -a -G dialout $USER

WSL2 (Windows Subsystem for Linux)

USB passthrough required: 1. Install usbipd-win 2. Attach USB reader to WSL: 

# In PowerShell (as Administrator)
usbipd list
usbipd bind --busid <BUSID>
usbipd attach --wsl --busid <BUSID>

Docker

USB device access required: 

# Add to Dockerfile
RUN apt-get update && apt-get install -y \
    pcscd libpcsclite-dev python3-dev swig

# Run with device access
docker run --device=/dev/bus/usb:/dev/bus/usb --privileged ...

Compatibility

Tested Readers

  • Generic USB CCID readers
  • Gemalto readers
  • ACS ACR122U

Known Issues

  • Some older card readers may have compatibility issues
  • Non-CCID readers may require additional drivers

Card Compatibility

  • Thai National ID cards issued after 2010 work well
  • Older cards (pre-2010) may have issues
  • New cards with updated chip work best