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.
- The system encounters a
- Troubleshooting steps:
- Stop any running antivirus programs.
- 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.
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:
- Reboot the Windows VM weekly.
- Keep the Windows VM updated.
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.
- Navigate to the Server Properties panel of the VM hosting SQL and select Database Settings (see the red box in the diagram).
- Record the location of the data and the logs (see the blue boxes).
- 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.
- Manually delete the SQL data and log files.
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:
Error in SOTI Identity (v2024.0.1):
- Troubleshooting steps:
- 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.
- Check for certificate issues.
- For example, an expired or invalid GoDaddy certificate on the SOTI Connect MS server.
- 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.
- For example,
- SOTI Connect is already registered to an instance of SOTI Identity, and you are trying to register with
another SOTI Identity
tenant.
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.
- 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.
- 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.
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:
- On the VM with the Management Server (MS) installed, open the PowerShell application in Administrator mode and navigate to the installer folder.
- 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. - For SQL
authentication:
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:
- Run the SOTI Connect installer as an administrator.
- Press CTRL + Double-click on the installer window to reveal the
Repair DTD option.
- 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".
- 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:
- Prevention:There are no workarounds for this specific issue since the action becomes genuinely unavailable on the OEM side. However, to prevent such situation:
- Delete the "Unavailable" action.
- Reconfigure the rule to exclude any rule or configuration that has "Unavailable" actions.
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
, or manually update the PA version by running the installer on the target machine.