Troubleshooting SOTI Connect

This section provides information on troubleshooting SOTI Connect installation/ upgrade errors.

Services Fail to Start During the Installation Process

  • Symptoms:
    • The system encounters a "Cannot start service" error during installation.

      SOTI Connectservice not started

  • Troubleshooting steps:
    1. Stop any running antivirus programs.
    2. Re-run the SOTI Connect installer.

Unable to Access SATO Printer via Hostname when Using Device Registry

  • Symptoms:
    • IPv4 mode is static, with a specified static IP and a specified hostname. However, the printer is inaccessible by hostname.
  • Troubleshooting steps:
    • If the hostname is a Dynamic Host Configuration Protocol (DHCP) hostname, set IPv4 mode to DHCP.
Restriction: Do not use static mode or static IP with a printer that uses a DHCP hostname. If you use static mode or static IP, the provided DHCP hostname cannot connect to the printer.

SOTI Connect becomes Slow or Unresponsive on Windows Virtual Machines (VM)

  • Symptoms:
    • The machine gradually becomes slow or unresponsive on a Windows VM that SOTI Connect is running on.
  • Troubleshooting steps:
    1. Reboot the Windows VM weekly.
    2. Keep the Windows VM updated.
Tip: Windows operating systems do not always automatically release all resources, which can lead to gradual performance degradation in Windows virtual machines. To restore optimal performance, consider rebooting the VM periodically to reset resource allocation and utilization.

SOTI Connect Installation Fails During the Database Data Deletion Step, Resulting in a Rollback Error

  • Symptoms:
    • During the SQL connection step of a SOTI Connect installation, selecting the database data deletion checkbox does not delete data and leads to a rollback error.
    • The following entries appear in the installer logs:
      2023-07-25 17:48:59,992 [ERROR] [ 8] Installer - Database migration failed and the
      installation/update cannot be continued. Please contact support for further assistance.
      2023-07-25 17:48:59,992 [ERROR] [ 8] Installer - Installation failed
      System.Exception: Database migration failed and the installation/update cannot be continued.
      Please contact support for further assistance.
  • Troubleshooting Steps:
    • Manually delete the SQL data and log files.
      1. Navigate to the Server Properties panel of the VM hosting SQL and select Database Settings (see the red box in the diagram).
      2. Record the location of the data and the logs (see the blue boxes).

        The Database Settings tab shows the location of data and log files

      3. Navigate to the data and log directories and delete all files in those directories.
        Important: Delete only the file contents of the data and log folders, not the data and log folders themselves.

Unable to Connect SOTI Identity with SOTI Connect

  • Symptoms:
    • Affected versions: SOTI Connect 2024.0 and later.
    • While attempting to add SOTI Connect to a SOTI Identity tenant, the following errors occur:

      Error in SOTI Connect:

      SOTI Connect errors

      Error in SOTI Identity (v2024.0.1):

      SOTI Identity errors

  • Troubleshooting steps:
    1. SOTI Connect is already registered to an instance of SOTI Identity, and you are trying to register with another SOTI Identity tenant.
      • Locate the first connection and delete it from the SOTI Identity console.
    2. Check for certificate issues.
      • For example, an expired or invalid GoDaddy certificate on the SOTI Connect MS server.
    3. Check for the wrong Fully Qualified Domain Name (FQDN) in the SOTI Connect installation.
      • For example, "SotiConnect20" instead of "SotiConnect20.soticonnect.com".
        Note: The FQDN is passed to SOTI Identity and SOTI Identity uses it to call back to SOTI Connect. If the FQDN is wrong, SOTI Identity cannot reach SOTI Connect.

Database Migration Fail: 2024.0 to 2024.1.0.7405

  • Symptoms:
    • Affected versions: SOTI Connect 2024.0 and later
    • Upgrading from SOTI Connect 2024.0 to 2024.1.0.7405 may have an edge case where database migration fails and causes a rollback.

      SOTI Connect upgrade error

  • Troubleshooting steps:
    Before updating, run the following SQL script to prepare the SOTI Connect database.
    use SotiConnectManagementServer
    
    IF OBJECT_ID('tempdb..#removeJsonMetadata') IS NOT NULL
    	DROP PROCEDURE #removeJsonMetadata
    GO
    
    CREATE PROCEDURE #removeJsonMetadata
    @JsonText nvarchar(max),
    @Result nvarchar(max) OUTPUT
    as 
    	declare @idBegin int = 0;
    	declare @idEnd int = 0;
    	select @idBegin = CHARINDEX('"$id":"', @JsonText, @idBegin)
    	WHILE @idBegin > 0
    	BEGIN
    		select @idEnd = @idBegin +  LEN('"$id":"')
    		select @idEnd = CHARINDEX('"', @JsonText, @idEnd)
    		select @idEnd = case when SUBSTRING(@JsonText, @idEnd + 1, 1) = ',' then @idEnd + 2 else @idEnd + 1 end
    		select @JsonText = REPLACE(@JsonText, SUBSTRING(@JsonText, @idBegin, @idEnd - @idBegin), '');
    		select @idBegin = CHARINDEX('"$id":"', @JsonText, @idBegin)
    	END
    	select @Result = @JsonText
    RETURN
    GO
    
    
    declare @JsonText nvarchar(max)
    
    DECLARE employee_cursor CURSOR FOR
      SELECT RuleJson
      FROM   [SotiConnectManagementServer].[dbo].[Rules]
    
    OPEN employee_cursor;
    FETCH NEXT FROM employee_cursor INTO @JsonText
    WHILE @@FETCH_STATUS = 0
      BEGIN  
    	  exec #removeJsonMetadata @JsonText, @JsonText output
          UPDATE [SotiConnectManagementServer].[dbo].[Rules]
          SET    RuleJson = @JsonText
          WHERE  CURRENT OF employee_cursor;
    
          FETCH NEXT FROM employee_cursor INTO @JsonText
      END;
    CLOSE employee_cursor;
    DEALLOCATE employee_cursor; 

Use of Custom Attribute Macros Resulting in Corrupted Certificate Templates

  • Symptoms:
    • Before SOTI Connect 2025.0, users could delete the custom attribute macro used in the subject alternative name of a certificate template. Following deletion, a corrupted value would appear in the certificate authority template. However, if the custom attribute was not deleted, the macro displayed correctly.
      Note: For SOTI Connect 2024.2, do not delete a custom attribute if it is referenced in a certificate authority template.
      Note: Make sure to delete the corrupt certificate template before upgrading SOTI Connect form 2024.2 to 2025.0, as it prevents the macros from displaying the custom attribute name.

Issue with Local Administrator Access

  • Symptoms:
    • If a SOTI Identity user with Administrator privileges changes the local administrator's role to a non-administrator and the connection between SOTI Identity and SOTI Connect is lost, no administrator remains on the local system.
  • Troubleshooting steps:

    To restore access, use the silent installer to inject an administrative flow and add a new local administrator. Follow the steps below:

    1. On the VM with the Management Server (MS) installed, open the PowerShell application in Administrator mode and navigate to the installer folder.
    2. Run the appropriate command based on your authentication method:
      • For SQL authentication:
        .\Soti.IoT.SilentInstaller.exe -databaseHost="databaseHost" -databaseUser="databaseUser" -databasePassword="databasePassword" -newadmin "NEW_ADMIN_USERNAME" "NEW_PASSWORD" 
      • For Windows authentication:
        .\Soti.IoT.SilentInstaller.exe -databaseHost="DatabaseHost" -databaseIntegratedSecurity -newadmin "NEW_ADMIN_USERNAME" "NEW_PASSWORD"
      Note: In the commands, enter the appropriate details according to your environment.

Unable to Retrieve Device Logs for an SNMP ZT400 Device

  • Symptoms:
    • Users are unable to retrieve device logs for a Zebra SNMP ZT400 device because the log file is too large.
  • Error message:
    • Couldn't complete action 'Retrieve Device Logs' on device(s) 'Zebra SNMP ZT400 Series Thermal Printer 2'.
  • Troubleshooting steps:

    Set the log size to a maximum of 10KB using the Change Logging Configuration device action to make sure the device logs are retrievable.

REST Simulation Unable to Send Alerts to the WebHook Receiver

  • Symptoms:
    • REST simulator devices are unable to send alerts to the WebHook receiver.
  • Error message:
    • [ERROR] [45]  ChannelService - Exception in trying to send alerts System.Net.Http.HttpRequestException: 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.
  • Troubleshooting steps:

    When installing or updating the REST Protocol Adapter (PA) using the silent installer, the Webhook receiver URL defaults to the private address: https://+:5551/

    For devices or simulators hosted on different machines than the REST PA installation, replace the + symbol with the REST PA machine's FQDN in the installer configuration XML before running the silent installer.

DTD Repair Failure During SOTI Connect Upgrade

  • Symptoms:
    • Device Type Definition (DTD) Repair is utilized when SOTI Connect changes the semantic ID of a property for a device. During any update, the installer automatically runs DTD Repair with a timeout of 5 minutes. If the repair process is not completed within this time-frame, an explicit warning message displays in the installer UI indicating that DTD Repair has failed.
  • Troubleshooting steps:
    Users encountering this error must run Repair DTD from the installer manually, as it does not time out. To run Repair DTD:
    1. Run the SOTI Connect installer as an administrator.
    2. Press CTRL + Double-click on the installer window to reveal the Repair DTD option.

      Repair DTD option

    3. Choose Repair DTD and follow the installer instructions.
    Important: Users must run Repair DTD using the installer corresponding to their current version of SOTI Connect (the installer which received the error) before updating to a new version. Otherwise, Repair DTD does not execute during the upgrade process.

Zebra SNMP Alert IDs - Rules Fail to Trigger with Specific Alert ID Conditions

  • Symptoms:
    • Some Zebra SNMP devices fail to trigger SOTI Connect when using certain alert IDs in Rules. This issue originates from the device.
  • Prevention:

    Older SNMP printers do not support all Alerts. Verify that your device supports the specific Alerts before using the corresponding alert IDs in SOTI Connect.

Unavailable Actions After Upgrading to SOTI Connect 2025.0

  • Symptoms:
    • Before SOTI Connect version 2025.0, any changes to the supported actions on some devices resulted in those specific actions becoming obsolete, causing the rules/configurations utilizing these actions to stop working. Starting with version 2025.0, SOTI Connect introduces the action state "Unavailable." Whenever SOTI Connect no longer supports a specific action on a particular device type, the action will be marked as "Unavailable". This can occur in scenarios such as:
      • The OEM has discontinued support for action X.
      • A specific OEM model does not support action X, which is otherwise supported by all other OEM models. To support common properties/actions, SOTI Connect marks the action as "Unavailable".
  • Prevention:
    There are no workarounds for this specific issue since the action becomes genuinely unavailable on the OEM side. However, to prevent such situation:
    1. Delete the "Unavailable" action.
    2. Reconfigure the rule to exclude any rule or configuration that has "Unavailable" actions.
Note: In some rare cases, an action that became "Unavailable" may become supported again. Confirm this by searching for the action again for the specific device type in use.

Automatic Remote Protocol Adapter (PA) Update Failures

  • Symptoms:
    • For SOTI Connect versions 2025.0 and 2025.0.1, automatic PA updates may fail when installing SOTI Connect in environments with network speed limitations (e.g., excessive PAs or restricted load balancer throughput).
  • Prevention:

    As a workaround, you can manually trigger the remote PA update from Administration > System Architecture, or manually update the PA version by running the installer on the target machine.