Troubleshooting

Common Issues and Solutions

Even with careful installation and configuration, you may occasionally encounter issues. This section provides solutions to the most common problems users face, helping you quickly resolve issues and maintain productivity.

Application Won't Start

Windows

If SoftSDC fails to launch on Windows:

1. Run as Administrator - Right-click the application icon and select "Run as Administrator"
2. Check Event Viewer - Open Windows Event Viewer for specific error messages
3. Verify Dependencies - Ensure .NET Framework 4.7.2+ is installed
4. Check Antivirus - Temporarily disable antivirus to rule out blocking

macOS

On macOS, the most common cause is the security system blocking the application:

1. Open System Preferences > Security & Privacy
2. Look for a message about SoftSDC being blocked
3. Click "Open Anyway" to authorize the application
4. Verify you have the latest version compatible with your macOS version

Linux

1. Run from Terminal - Execute the application from terminal to see error messages
2. Check Dependencies - Verify all required packages are installed
3. Verify PC/SC Daemon - Check if pcscd is running:

   sudo systemctl status pcscd

4. Start PC/SC if needed:

   sudo systemctl start pcscd

General Solutions

For all platforms:

• Restart your device - Clear temporary issues or conflicting processes
• Check disk space - Ensure sufficient free space (minimum 500MB recommended)
• Update the application - Install the latest version
• Review logs - Check application logs in the data directory

Card Reader Detection Problems

Basic Troubleshooting

Start with these fundamental checks:

1. Verify Physical Connection

   • USB cable firmly connected at both ends
   • Try different USB ports
   • USB 3.0 ports (blue) often provide more stable power

2. Test with Another Device

   • Try the reader with a different USB device (like a flash drive)
   • Confirms the USB port is functioning

Windows

1. Open Device Manager
2. Look under "Smart card readers"
3. If you see a yellow warning icon:
   • Right-click and select "Update driver"
   • Or uninstall and reconnect the device

macOS

1. Open System Information (About This Mac > System Report)
2. Go to USB section
3. Confirm the reader appears in the list
4. Check if any permissions need to be granted in Security & Privacy

Linux

1. List USB devices:

   lsusb

   Your reader should appear in this list

2. Test PC/SC subsystem:

   sudo pcsc_scan

3. Check permissions:

   ls -l /dev/bus/usb/

Android

1. Verify OTG Support - Check device specifications or use an OTG checker app
2. Enable OTG in Settings - Some devices require manual OTG enabling
3. Test OTG Adapter - Try with other USB devices (flash drive)
4. Grant USB Permissions - Accept permission dialog when prompted
5. Try Different Adapter - Some OTG adapters are incompatible

License Activation Problems

Network Issues

License activation failures usually stem from network connectivity:

1. Verify Internet Connection

   • Open a web browser and navigate to any website
   • Test connectivity to license servers

2. Check Firewall

   • Ensure SoftSDC can make outbound HTTPS connections on port 443
   • Add exceptions for Cryptlex license servers:
     • 52.223.22.71
     • 35.71.188.31
     • https://api.cryptlex.com:443

3. Verify System Time

   • Ensure date and time are correct
   • Enable "Set time automatically"
   • Significant time discrepancies cause SSL certificate validation failures

Proxy Configuration

If you're behind a proxy server:

1. Configure proxy settings in SoftSDC settings
2. Ensure proxy allows HTTPS connections
3. Check if proxy requires authentication

Corporate Firewalls

In corporate environments:

1. Whitelist Required Endpoints - Add Cryptlex servers to firewall whitelist
2. Request IT Assistance - Provide IT with the firewall requirements from installation guide
3. Use Offline Activation - Contact support for offline activation options if online activation is blocked

License Errors

• "License already activated" - License may be in use on another device. Deactivate from previous device first
• "Invalid license key" - Verify you copied the entire key correctly
• "License expired" - Renew your license at softsdc.com
• "Trial already used" - Trial is node-locked; cannot be reset

Port Conflicts

If you receive an error that the API port is already in use:

Identify the Conflicting Process

Windows:

netstat -ano | findstr :8431

macOS/Linux:

lsof -i :8431

Solutions

1. Stop the Conflicting Application

   • Identify and close the application using the port

2. Change SoftSDC Port

   • Go to Settings > Network
   • Change API port to an available port (e.g., 8081, 9090)
   • Update your POS system configuration to use the new port

3. Kill the Process (if necessary):

   • Windows: taskkill /PID [process_id] /F
   • macOS/Linux: kill -9 [process_id]

Smart Card Errors

PIN Issues

Problem: PIN verification fails (Error 2100)

Solutions:

• Verify you're entering the correct PIN
• Check if caps lock is enabled
• Ensure PIN is entered as numbers only
• Note how many attempts remain (visible in error message)

Problem: Card locked (Error 2110)

Solution:

• Contact Tax Authority immediately
• Card must be reset by authorized personnel
• Do not attempt further PIN entries

Card Not Detected

Problem: Smart card not recognized (Warning 1300)

Checklist:

• Ensure card is fully inserted in reader
• Check card for physical damage
• Try removing and reinserting card
• Clean card contacts with soft, dry cloth
• Test with different smart card if available

Secure Element Errors

Problem: Cannot connect to SE (Error 2220)

Steps:

1. Remove and reinsert smart card
2. Restart SoftSDC service
3. Try different USB port for reader
4. Check reader drivers are installed
5. Test card in different reader if available

Problem: SE Locked (Error 2210)

Solution:

• Perform audit immediately
• No invoices can be processed until audit completes
• Contact support if audit fails

Invoice Processing Issues

Validation Errors (28xx)

Error 2800 - Field Required

• Review API request to ensure all mandatory fields are present
• Check API documentation for required fields

Error 2806 - Invalid Data Format

• Verify date/time formats are ISO 8601
• Check numeric values are properly formatted
• Ensure PIN contains only digits 0-9

Error 2310 - Invalid Tax Labels

• Verify tax labels match current tax rates
• Check /api/v3/status for valid labels
• Ensure labels are correctly assigned to items

Configuration Issues

Error 2400 - Not Configured

Solutions:

1. Run "Download init commands" from Actions menu
2. Verify internet connection is available
3. Check if tax rates are downloaded
4. Ensure verification URL is configured

Audit Issues

Warning 1400 - Audit Required

Actions:

• Schedule audit as soon as possible
• You have ~25% capacity remaining
• Plan for system downtime during audit

Warning 1100 - Storage 90% Full

Actions:

• Perform audit to free storage
• Check disk space on device
• Review and archive old logs if needed

Performance Issues

Slow Response Times

1. Check System Resources

   • Monitor CPU and memory usage
   • Close unnecessary applications
   • Ensure adequate free disk space (10%+ recommended)

2. Review Settings

   • Reduce refresh rate frequency if set too high
   • Disable verbose logging if enabled
   • Check background worker thread settings

3. Network Performance

   • Test internet speed
   • Check for network congestion
   • Verify stable connection to Tax Authority servers

High Memory Usage

1. Restart the Service - Clear accumulated memory
2. Check Log Settings - Reduce logging level from Debug/Verbose to Info
3. Review Data Retention - Archive old invoices if retention period is very long

Connection Issues

Internet Connectivity

Symptoms: Cannot sync time, submit invoices, or download commands

Solutions:

1. Verify internet connection works in browser
2. Check firewall/antivirus isn't blocking SoftSDC
3. Test DNS resolution
4. Try different network (mobile hotspot) to isolate issue
5. Check if VPN is interfering

Tax Authority Server

Symptoms: Cannot connect to TaxCore API

Solutions:

1. Check status message for specific endpoint failures
2. Verify Tax Authority services are operational
3. Check server URLs in environment parameters
4. Ensure proper SSL/TLS certificate validation
5. Review any proxy/firewall blocking HTTPS traffic

Data Issues

Missing Invoices

Symptoms: Invoice created but not visible in history

Check:

1. Review application logs for processing errors
2. Check if invoice is in "unconfirmed" status
3. Verify time synchronization is working
4. Look for storage space issues

Synchronization Problems

Symptoms: Invoices not confirming, unconfirmed receipts growing

Solutions:

1. Ensure stable internet connection
2. Wait for reconciliation cycle (15-20 minutes)
3. Check for missing receipts in sequence
4. Review application logs for audit issues
5. Contact support if problem persists

Mobile-Specific Issues

Android Battery Drain

Solutions:

1. Adjust refresh rate to "Normal" or "Slow"
2. Connect to power during extended use
3. Review battery optimization settings
4. Ensure app has permission to run in background

Permissions Denied

Symptoms: Cannot access USB, storage, or notifications

Solutions:

1. Go to Settings > Apps > SoftSDC > Permissions
2. Enable all required permissions
3. Restart application after granting permissions

Getting Additional Help

If these solutions don't resolve your issue:

1. Check Application Logs - Detailed error information
2. Review Recent Changes - OS updates, configuration changes
3. Test in Safe Mode - Rule out third-party interference
4. Contact Support - Use the support template with full system information

Preventive Measures

Best Practices to Avoid Issues

1. Regular Updates - Keep SoftSDC and OS updated
2. Monitor Warnings - Address warnings before they become errors
3. Schedule Audits - Perform regular audits before reaching limits
4. Backup Configuration - Export settings periodically
5. Test After Changes - Verify operation after configuration changes
6. Maintain Hardware - Keep card reader clean and properly connected
7. Stable Power - Use UPS for desktop installations
8. Monitor Storage - Ensure adequate free disk space
9. Time Sync - Keep automatic time synchronization enabled
10. Document Setup - Keep notes on custom configurations

Following these practices minimizes downtime and ensures smooth operation of your fiscal system.