Overview 


When connecting a device using Suprema G-SDK, the connection may fail due to environmental or configuration issues.


This article explains common connection errors that can occur between the device, the Device Gateway, and the application, and provides possible causes and solutions.


Before troubleshooting, you can increase the log level of the Device Gateway to 5 (DEBUG) in the config.json file, located in the same folder as the Device Gateway executable, to view detailed logs.



This setting can help identify the cause of the failure more accurately; however, note that the log volume will increase significantly, so it is recommended to use this setting only when necessary.

1. EULA.txt has not been found, or the Device Gateway itself does not run. 



Cause

The SDK cannot locate a valid license file.


Solution

Go to the Suprema G-SDK GitHub and download the EULA.txt file.

Place the downloaded EULA.txt file in the same directory as the Device Gateway.


2. Connection refused (No connection could be made because the target machine actively refused it.)


Case 1. Connection to Device Gateway refused



Cause

The client attempted to connect to the Device Gateway but the request was rejected on the specified port. This issue typically occurs if the Device Gateway service is not running or if the port is not actively listening for incoming connections.


Possible reasons

  • Device Gateway is not running.
  • Invalid port configuration.


Solution

  • Start the Device Gateway and confirm it is listening on the correct port.
  • Verify that the IP address and port are correctly configured in your connection settings. The Device Gateway's IP address and port can be checked in the rpc_server section of the config.json file.


Case 2. Connection to device refused



Cause

This occurs when the client attempts to connect to a device, but the device cannot connect to the device gateway. 


Possible reasons

  • When the Connection mode is set differently from the intended use case.


Solution

  • Please check that the Connection Mode is configured correctly for its intended purpose.
    (For example, if the server is requesting a connection to the device, the [Server to Device] mode should be configured on the device. Please check the link: Connect API: Connection Mode)


3. A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.



Cause

If the device is already connected to another server (for example, BioStar 2), it may not respond to the new connection request within the expected time frame. 


Possible reasons

  • The device is already connected to another server (for example, BioStar 2).


Solution

  • Disconnect the device from any other server (each device can connect to only one server at a time).


4. Cannot handshake the direct connection: Cannot receive the sync packet: Cannot receive packet: Timeout to read the start code ... i/o timeout



Cause

In Suprema G-SDK, communication occurs between the device and the Device Gateway, as well as between the client application and the Device Gateway. Even if the client disconnects from the Device Gateway, if the disconnection is not appropriately handled, the Device Gateway may still maintain the existing connection with the device.


As a result, when the client tries to reconnect, the handshake can fail, and this error may occur.


Possible reasons

  • The application closed its connection, but the Device Gateway continued to maintain its connection with the device.
  • The device is powered off, disconnected, or not on the network.


Solution

  • Ping the device to verify it's reachable: ping [Device IP]
  • To properly close the connection: 
    • 1. Add code to explicitly disconnect the device from the Device Gateway by calling.
    • 2. Close the communication channel after the disconnection:
connectSvc.disconnect(deviceID)
channel.close()
  • Restart the Device Gateway to clear any stale connections.
  • Reboot the device and retry.


5. Cannot SSL handshake: local error: tls: bad record MAC



Cause

SSL handshake failed between the server and the device due to a certificate mismatch.


Possible reasons

  • When an SSL connection is required but the device lacks an SSL certificate, or vice versa.
  • When the server and the device certificates do not match.


Solution

  • Upload a valid certificate that matches the SSL communication requirements, or perform a Factory Default to remove the existing certificate on the device.


6. Cannot start the TCP server: Only one usage of each socket address is normally permitted



Cause

The Device Gateway attempted to open a port (for example, 51212 or 51213) that is already in use by another process.


Solution

  • Check which process is using the port: 

            netstat -ano | findstr :51212

            tasklist /svc /FI "PID eq [PID]" // Show process and service linked to the PID

  • Stop or close the other application, or
  • Change the port number in config.json and restart the Device Gateway.


7. Peer name <IP> is not in peer certificate



Cause

This error occurs because the Device Gateway certificate was generated without including the correct IPv4 address in the "IPv4 Address" field during the initial certificate setup. As a result, when the client attempts to connect using that IP address, the  SSL verification fails because the IP address is not listed in the Device Gateway's certificate.


Solution

  • Recreate the Device Gateway certificate using the following command: device gateway -c
  • When prompted during the setup process, ensure that you enter the actual IP address that the Device Gateway will use in the "IPv4 Address" field.

  • Restart the Device Gateway after completing the certificate setup.


For the installation guide, please refer to this link: https://supremainc.github.io/g-sdk/gateway/install/