# Common Errors & FAQ

Here you can find some of the most common error messages and questions asked from Frends, and the common solutions and answers to them.

### Agent Installation & Service Errors <a href="#agent-installation-and-service-errors" id="agent-installation-and-service-errors"></a>

#### Cannot start service FrendsAgent$... Error 1053 <a href="#id-1.-cannot-start-service-frendsagentusd...-error-1053" id="id-1.-cannot-start-service-frendsagentusd...-error-1053"></a>

The Frends Agent service fails to start because the required .NET Runtime version is not installed or the wrong version is present on the agent machine.

Run `dotnet --info` to confirm the installed version. Install the .NET 8.0 [ASP.NET Core, an open-source web development framework | .NET](http://asp.net/) Core Runtime Hosting Bundle and Desktop Runtime x64, then re-run the agent installer.

#### Could not load file or assembly 'Microsoft.Extensions.Configuration.Abstractions' <a href="#id-2.-could-not-load-file-or-assembly-microsoft.extensions.configuration.abstractions" id="id-2.-could-not-load-file-or-assembly-microsoft.extensions.configuration.abstractions"></a>

Antivirus software is blocking one or more DLLs required by the agent, or the installer ZIP file was not unblocked before extraction.

Right-click the ZIP file → Properties → Unblock. Add the Frends Agent folder to your AV exclusion list. Run the installer as Administrator.

#### InstallAgentService failed <a href="#id-3.-installagentservice-failed" id="id-3.-installagentservice-failed"></a>

The credentials provided in `config.json` are incorrect, or the Windows user account for the agent service does not exist or lacks the necessary permissions.

Verify all credentials in `config.json`. Ensure the specified user account exists and has the required local permissions.

#### Failed to create user. ({error code} {username}) <a href="#id-4.-failed-to-create-user.-error-code-username" id="id-4.-failed-to-create-user.-error-code-username"></a>

The user account provided for the agent service has incorrect credentials or is missing required Windows rights.

Confirm the user is a member of the local Administrators group and has been granted "Log on as a service" and "Log on as a batch job" rights via Windows Local Security Policy.

#### Could not find configuration file <a href="#id-5.-could-not-find-configuration-file" id="id-5.-could-not-find-configuration-file"></a>

The installer was run directly from the ZIP archive without first extracting the contents to a dedicated folder.

Extract all contents of the installer ZIP into a separate folder, then run `Frends.Agent.WindowsInstaller.msi` from that location.

#### Could not retrieve value from cache for key currentProcesses. Clearing cache. + agent restart loop <a href="#id-6.-could-not-retrieve-value-from-cache-for-key-currentprocesses.-clearing-cache.--agent-restart-loo" id="id-6.-could-not-retrieve-value-from-cache-for-key-currentprocesses.-clearing-cache.--agent-restart-loo"></a>

The "Allow new agents to connect to Agent Group" option is enabled on a Windows on-premises agent, causing cache invalidation and restart loops. Antivirus scanning may amplify this.

Disable "Allow new agents to connect to Agent Group" in Agent Group → Advanced Settings. Add the Frends Agent folder to AV exclusions.

#### Security token did not have 'issuer' field set <a href="#id-7.-security-token-did-not-have-issuer-field-set" id="id-7.-security-token-did-not-have-issuer-field-set"></a>

The 'issuer' field is missing from the security token used for agent authentication, typically a NATS or Service Bus configuration issue.

Investigate the NATS or Service Bus token configuration. If the issue persists, contact Frends Support with the full token configuration details.

#### Unable to initialize database… The certificate chain was issued by an authority that is not trusted <a href="#id-8.-unable-to-initialize-database...-the-certificate-chain-was-issued-by-an-authority-that-is-not-tru" id="id-8.-unable-to-initialize-database...-the-certificate-chain-was-issued-by-an-authority-that-is-not-tru"></a>

The SQL Server's TLS certificate (e.g., from Amazon RDS or a private CA) is not trusted by the agent machine's certificate store.

Install the root and intermediate CA certificates from the SQL Server provider into the Windows certificate store on the agent machine.

#### Cannot open server 'sql-...' requested by the login. Client with IP '...' is not allowed <a href="#id-9.-cannot-open-server-sql-...-requested-by-the-login.-client-with-ip-...-is-not-allowed" id="id-9.-cannot-open-server-sql-...-requested-by-the-login.-client-with-ip-...-is-not-allowed"></a>

The SQL Server firewall is blocking the agent's IP address from establishing a connection.

Enable "Allow access to Azure services" in the SQL Server firewall settings, or explicitly add the agent's IP address to the allowed list.

#### The target principal name is incorrect. Cannot generate SSPI context. <a href="#id-10.-the-target-principal-name-is-incorrect.-cannot-generate-sspi-context" id="id-10.-the-target-principal-name-is-incorrect.-cannot-generate-sspi-context"></a>

A Kerberos ticket cache issue prevents Windows Authentication from working when the agent connects to a SQL Server Always On listener.

Run `klist purge` in PowerShell on the agent machine to clear the Kerberos ticket cache, then retry the connection.

#### Agent service won't start after reinstall (old client uninstalled, new installed) <a href="#id-11.-agent-service-wont-start-after-reinstall-old-client-uninstalled-new-installed" id="id-11.-agent-service-wont-start-after-reinstall-old-client-uninstalled-new-installed"></a>

Residual state from the previous agent installation remains, and Service Bus traffic may be blocked on ports 5671/5672.

Purge the agent's log database. Configure the Service Bus connection to use port 443 (WebSockets). Re-run the installer cleanly.

#### Agent does not appear in Frends UI / shows as disconnected <a href="#id-12.-agent-does-not-appear-in-frends-ui-shows-as-disconnected" id="id-12.-agent-does-not-appear-in-frends-ui-shows-as-disconnected"></a>

Firewall rules are blocking outbound traffic on Service Bus ports 5671 and 5672, preventing the agent from communicating with the control plane.

Add `;TransportType=AmqpWebSockets` to the Service Bus connection string in `appsettings.secrets.json` to force communication over port 443.

#### Cannot configure Web UI if log service not installed <a href="#id-13.-cannot-configure-web-ui-if-log-service-not-installed" id="id-13.-cannot-configure-web-ui-if-log-service-not-installed"></a>

The Frends configuration tool was run before the Log Service component was installed on the server.

Install the Log Service first, then re-run the Web UI configuration step.

#### Web UI installation fails: database scripts could not be executed (database '**REPLACE**') <a href="#id-14.-web-ui-installation-fails-database-scripts-could-not-be-executed-database-replace" id="id-14.-web-ui-installation-fails-database-scripts-could-not-be-executed-database-replace"></a>

The installer user account does not have write permission to `\\Program Files\\Frends Neon\\settings\\`, preventing the database setup scripts from executing.

Grant the account running the installer write permissions to the Frends Neon settings folder, then re-run the installation.

### Agent Upgrade / Update Errors <a href="#agent-upgrade-update-errors" id="agent-upgrade-update-errors"></a>

#### Access to the path '...\Dapper.dll' is denied <a href="#id-15.-access-to-the-path-...-dapper.dll-is-denied" id="id-15.-access-to-the-path-...-dapper.dll-is-denied"></a>

An old assembly load context was not released after a process version update, leaving a DLL file locked and preventing cleanup of old process directories.

Create a new process version using updated task versions, restart the agent, then redeploy the process. The locked context will be released on restart.

#### Failed to delete process directory... Access to the path '...' is denied <a href="#id-16.-failed-to-delete-process-directory...-access-to-the-path-...-is-denied" id="id-16.-failed-to-delete-process-directory...-access-to-the-path-...-is-denied"></a>

During an upgrade, a DLL in an old process version directory is still locked by the agent process and cannot be deleted immediately.

Restart the Frends Agent service after the upgrade completes. The cleanup will finish successfully on the next start.

#### The certificate received from the remote server was issued by an untrusted certificate authority (post-upgrade) <a href="#id-17.-the-certificate-received-from-the-remote-server-was-issued-by-an-untrusted-certificate-authority" id="id-17.-the-certificate-received-from-the-remote-server-was-issued-by-an-untrusted-certificate-authority"></a>

Newer .NET versions enforce stricter certificate validation. After an upgrade, the agent may refuse to connect to a database whose certificate was previously accepted.

Add `TrustServerCertificate=True` to the database connection string in the Frends UI, then download a new installation package and reinstall the agent.

#### Method not found: 'System.Linq.IQueryable...' after upgrade <a href="#id-18.-method-not-found-system.linq.iqueryable...-after-upgrade" id="id-18.-method-not-found-system.linq.iqueryable...-after-upgrade"></a>

A platform-level dependency (e.g., a NuGet library) was updated as part of the Frends upgrade, creating a version conflict with a custom task compiled against the older version.

Recompile the custom task against the dependency versions used by the new Frends platform version. Update relevant NuGet packages in the custom task project accordingly.

#### External process execution failed... Installing the update failed. Server version is not compatible with client version. <a href="#id-19.-external-process-execution-failed...-installing-the-update-failed.-server-version-is-not-compati" id="id-19.-external-process-execution-failed...-installing-the-update-failed.-server-version-is-not-compati"></a>

A third-party server component (e.g., Primus) has a version mismatch with its client, making them incompatible after the Frends upgrade.

Update both the server and client components to matching, compatible versions.

#### Unused assembly load contexts could not be unloaded (agent log warning) <a href="#id-20.-unused-assembly-load-contexts-could-not-be-unloaded-agent-log-warning" id="id-20.-unused-assembly-load-contexts-could-not-be-unloaded-agent-log-warning"></a>

Certain tasks within a process prevent the .NET assembly load context from being released, leaving residual contexts in memory.

Update all tasks within the affected process to their latest versions and restart the agent.

#### License verification failed: Invalid signature <a href="#id-21.-license-verification-failed-invalid-signature" id="id-21.-license-verification-failed-invalid-signature"></a>

An old ACC 1.0 license file is present in the license folder during an upgrade to ACC 2.0, causing a signature validation conflict.

Remove the old license file from the `/License` folder before running the upgrade.

#### DMN execution failure: Could not load file or assembly 'NLog, Version=4.0.0.0...' <a href="#id-22.-dmn-execution-failure-could-not-load-file-or-assembly-nlog-version-4.0.0.0" id="id-22.-dmn-execution-failure-could-not-load-file-or-assembly-nlog-version-4.0.0.0"></a>

The NLog dependency required for DMN execution is missing in the cross-platform agent package.

This is a known bug fixed in a later cross-platform agent release. Upgrade to the latest available agent version.

### Connectivity & Network Errors <a href="#connectivity-and-network-errors" id="connectivity-and-network-errors"></a>

#### Agent shows as gray / offline; scheduled triggers inactive <a href="#id-23.-agent-shows-as-gray-offline-scheduled-triggers-inactive" id="id-23.-agent-shows-as-gray-offline-scheduled-triggers-inactive"></a>

The agent has lost its connection to the Azure Service Bus, typically due to a transient network disruption, which causes the Frends UI to show the agent as offline.

Check OS Event Logs on the agent server for connection errors. Restart the Frends Agent service. If the issue persists, reboot the agent host machine.

#### Amqp:resource-limit-exceeded or local-idle-timeout expired <a href="#id-24.-amqp-resource-limit-exceeded-or-local-idle-timeout-expired" id="id-24.-amqp-resource-limit-exceeded-or-local-idle-timeout-expired"></a>

The Azure Service Bus resource quota has been reached under high concurrency, or idle connections are being timed out by the Service Bus.

Review and tune the concurrency settings in the Agent Group configuration. If the issue persists under normal load, escalate to R\\\&D with diagnostics.

#### Channel to 'frends\\\_heartbeatlog'... Timed out waiting for acks <a href="#id-25.-channel-to-frends-_heartbeatlog...-timed-out-waiting-for-acks" id="id-25.-channel-to-frends-_heartbeatlog...-timed-out-waiting-for-acks"></a>

The Frends agent is unable to receive acknowledgments from RabbitMQ within the expected time, indicating a network delay or RabbitMQ health issue.

Investigate network stability between the agent and the RabbitMQ host. Confirm RabbitMQ is accessible and healthy. Address any underlying network bottlenecks.

#### Firewall log: First packet isn't SYN (intermittent SQL drops from PaaS agent) <a href="#id-26.-firewall-log-first-packet-isnt-syn-intermittent-sql-drops-from-paas-agent" id="id-26.-firewall-log-first-packet-isnt-syn-intermittent-sql-drops-from-paas-agent"></a>

The firewall connection timeout is shorter than the agent's database connection lifetime, causing the firewall to silently drop idle connections mid-session.

Increase the firewall connection timeout, or enable TCP keepalives by appending the appropriate option to the database connection string.

#### A network-related or instance-specific error occurred while establishing a connection to SQL Server <a href="#id-27.-a-network-related-or-instance-specific-error-occurred-while-establishing-a-connection-to-sql-ser" id="id-27.-a-network-related-or-instance-specific-error-occurred-while-establishing-a-connection-to-sql-ser"></a>

The Frends agent or UI cannot reach the SQL Server due to an incorrect server name in the connection string, a missing firewall rule, or an authentication problem.

Verify the connection string is correct. Ensure port 1433 is open from the agent to the SQL Server. Confirm the SQL user has the correct database permissions.

#### REST APIs published to agent are not accessible externally <a href="#id-28.-rest-apis-published-to-agent-are-not-accessible-externally" id="id-28.-rest-apis-published-to-agent-are-not-accessible-externally"></a>

Inbound firewall rules have not been configured to allow traffic on the agent's API port, blocking external clients from reaching published APIs.

Open the configured agent API port (e.g., 443) for inbound traffic in the firewall or network security group of the agent server.

#### Agent cannot connect to Agent Group in Kubernetes <a href="#id-29.-agent-cannot-connect-to-agent-group-in-kubernetes" id="id-29.-agent-cannot-connect-to-agent-group-in-kubernetes"></a>

The "Allow new agents to connect to Agent Group" option is not enabled in the Agent Group settings, preventing new Kubernetes-based agents from joining.

Enable this option in Agent Group → Advanced Settings in the Frends Control Panel.

#### Did not get a response from the remote subprocess call within the preconfigured timeout <a href="#id-30.-did-not-get-a-response-from-the-remote-subprocess-call-within-the-preconfigured-timeout" id="id-30.-did-not-get-a-response-from-the-remote-subprocess-call-within-the-preconfigured-timeout"></a>

A remote subprocess call is taking too long, often caused by transferring large payloads (10 MB+) over the Service Bus or a transient network disruption.

Avoid using remote subprocesses for large data payloads — use direct HTTPS calls to on-premises agents instead. Implement "Retry on failure" for transient errors. Reinstall both agents simultaneously if the issue follows an upgrade.

#### SignatureDoesNotMatch from S3BlobStore during remote subprocess <a href="#id-31.-signaturedoesnotmatch-from-s3blobstore-during-remote-subprocess" id="id-31.-signaturedoesnotmatch-from-s3blobstore-during-remote-subprocess"></a>

The `StorageType` configuration for the blob storage used during remote subprocess execution is incorrect or the S3 access credentials are mismatched.

Verify the `StorageType` value and confirm that the S3 access key and secret are correctly configured in the agent's blob storage settings.

#### SFTP transfer failed: Unable to establish socket... connected party did not properly respond <a href="#id-32.-sftp-transfer-failed-unable-to-establish-socket...-connected-party-did-not-properly-respond" id="id-32.-sftp-transfer-failed-unable-to-establish-socket...-connected-party-did-not-properly-respond"></a>

The SFTP server is unreachable or not responding within the connection timeout, typically due to a network outage or firewall rule.

Verify the SFTP server is reachable from the agent machine. Confirm firewall rules allow outbound traffic on port 22. Implement retry logic within the process.

#### SFTP transfer failed: Destination directory '...' was not found <a href="#id-33.-sftp-transfer-failed-destination-directory-...-was-not-found" id="id-33.-sftp-transfer-failed-destination-directory-...-was-not-found"></a>

The target directory specified in the SFTP task does not exist on the remote SFTP server.

Create the destination directory on the SFTP server prior to running the process, or add a directory-creation step at the start of the process.

### SSL / TLS / Certificate Errors <a href="#ssl-tls-certificate-errors" id="ssl-tls-certificate-errors"></a>

#### The request was aborted: Could not create SSL/TLS secure channel. <a href="#id-34.-the-request-was-aborted-could-not-create-ssl-tls-secure-channel" id="id-34.-the-request-was-aborted-could-not-create-ssl-tls-secure-channel"></a>

The TLS version or cipher suite required by the remote server is not supported or not enabled on the Frends agent machine.

Check TLS configuration on both ends. Upgrade Frends and the OS if possible. If a legacy TLS version is unavoidable, enable it via Windows registry settings and restart.

#### The remote certificate is invalid because of errors in the certificate chain: NotTimeValid <a href="#id-35.-the-remote-certificate-is-invalid-because-of-errors-in-the-certificate-chain-nottimevalid" id="id-35.-the-remote-certificate-is-invalid-because-of-errors-in-the-certificate-chain-nottimevalid"></a>

An intermediate or chain certificate in the trust path has expired, making the full certificate chain unverifiable.

Obtain and install the updated intermediate certificate from the certificate provider in the Windows certificate store on the server.

#### TLS errors after VM OS upgrade (e.g., Windows Server 2019 → 2022) <a href="#id-36.-tls-errors-after-vm-os-upgrade-e.g.-windows-server-2019-2022" id="id-36.-tls-errors-after-vm-os-upgrade-e.g.-windows-server-2019-2022"></a>

The newer Windows Server version disables TLS 1.0/1.1 and older cipher suites by default, causing connections to legacy systems to fail.

Update target systems to use TLS 1.2 or higher. If you must maintain compatibility with a legacy system, re-enable the required TLS version via a PowerShell registry script and restart the VM.

#### Unknown SSL protocol error in API calls <a href="#id-37.-unknown-ssl-protocol-error-in-api-calls" id="id-37.-unknown-ssl-protocol-error-in-api-calls"></a>

A cipher suite mismatch exists between the Frends server and the remote client; the client is requesting a cipher that the server does not support or has disabled.

Identify the cipher suites required by both parties. Enable the required cipher suite on the server, or update the client to use a mutually supported cipher.

#### LogService email SSL/TLS error on SMTP port 587 <a href="#id-38.-logservice-email-ssl-tls-error-on-smtp-port-587" id="id-38.-logservice-email-ssl-tls-error-on-smtp-port-587"></a>

The SMTP client is not configured to use STARTTLS, which is required for port 587. Using implicit SSL settings on this port causes a handshake failure.

Set the SMTP client's secure socket option to `SecureSocketOptions.StartTls` for port 587. Use port 465 with implicit SSL if STARTTLS is not supported.

#### SMTP certificate trust failure after certificate renewal <a href="#id-39.-smtp-certificate-trust-failure-after-certificate-renewal" id="id-39.-smtp-certificate-trust-failure-after-certificate-renewal"></a>

After renewing an SMTP server's TLS certificate, the new root or intermediate CA certificate is not present in the Windows certificate store on the Frends server.

Install the updated root and intermediate CA certificates in the Windows certificate store. Review Windows Event Viewer → System log for Schannel errors to identify the exact missing certificate.

#### Frends.LDAP.SearchObjects: Cannot connect to LDAP / Active Directory <a href="#id-40.-frends.ldap.searchobjects-cannot-connect-to-ldap-active-directory" id="id-40.-frends.ldap.searchobjects-cannot-connect-to-ldap-active-directory"></a>

The LDAP task is configured with the wrong port or conflicting SSL/TLS settings, preventing a successful connection to the directory server.

Use port 636 with `SecureSocketLayer=true` for LDAPS connections. Use port 389 for plain LDAP. Do not enable both SSL and TLS options simultaneously.

#### SQLite error: disk or database is full <a href="#id-41.-sqlite-error-disk-or-database-is-full" id="id-41.-sqlite-error-disk-or-database-is-full"></a>

The disk on the agent server is full, or the SQLite database file used by the agent has reached its size limit.

Free up disk space on the agent server. For production use, migrate from SQLite to SQL Server. Review and tighten log retention settings to prevent recurrence.

#### The SSL connection could not be established, see inner exception <a href="#id-42.-the-ssl-connection-could-not-be-established-see-inner-exception" id="id-42.-the-ssl-connection-could-not-be-established-see-inner-exception"></a>

The remote server's SSL certificate is not trusted by the agent, or a TLS protocol version mismatch is preventing the handshake from completing.

Verify the full certificate chain is trusted on the agent machine. Check that no firewall or proxy is intercepting and altering the TLS handshake.

### &#x20;Process Execution Errors <a href="#process-execution-errors" id="process-execution-errors"></a>

#### Execution Timeout Expired. The timeout period elapsed prior to completion... <a href="#id-43.-execution-timeout-expired.-the-timeout-period-elapsed-prior-to-completion" id="id-43.-execution-timeout-expired.-the-timeout-period-elapsed-prior-to-completion"></a>

A task or operation did not complete within its configured timeout period, often because a target system is slow or unresponsive.

Increase the timeout value in the task's settings. Optimize the process or query logic. Investigate the health and response time of the target system.

#### HttpRequest was canceled, most likely due to a timeout. <a href="#id-44.-httprequest-was-canceled-most-likely-due-to-a-timeout" id="id-44.-httprequest-was-canceled-most-likely-due-to-a-timeout"></a>

An HTTP request to an external API or service was not completed within the configured timeout period.

Increase the timeout value in the HTTP task options. Implement retry logic with exponential backoff. Verify the external service is available and performing normally.

#### Exception of type 'System.OutOfMemoryException' was thrown. <a href="#id-45.-exception-of-type-system.outofmemoryexception-was-thrown" id="id-45.-exception-of-type-system.outofmemoryexception-was-thrown"></a>

The Frends Agent process has run out of available memory, commonly caused by loading large files entirely into memory, excessive logging on high-volume processes, or a memory leak in a custom task.

Redesign processes to handle data in batches or use streaming. Reduce the log level for high-volume processes. Ensure custom tasks properly dispose of objects. Increase the RAM on the agent server if resource constraints are the root cause.

#### The process cannot access the file '...' because it is being used by another process. <a href="#id-46.-the-process-cannot-access-the-file-...-because-it-is-being-used-by-another-process" id="id-46.-the-process-cannot-access-the-file-...-because-it-is-being-used-by-another-process"></a>

A file being processed is locked by another process — such as antivirus software, a backup agent, or a concurrent Frends process instance.

Move the file from the Failed directory back to the working directory and re-run. Add retry logic to the process. Set "Maximum concurrent instances" to 1 on the trigger to prevent race conditions.

#### No source files found from directory '...' <a href="#id-47.-no-source-files-found-from-directory" id="id-47.-no-source-files-found-from-directory"></a>

A concurrent process instance has already consumed the available files from the source directory, or the source directory is genuinely empty.

Set the trigger's "Maximum concurrent instances" to 1. Verify the destination directory for unexpectedly moved files. Clean up any orphaned `.8CO` temporary files.

#### Failure in RenameSourceFileBeforeTransfer: Could not find file '...' <a href="#id-48.-failure-in-renamesourcefilebeforetransfer-could-not-find-file" id="id-48.-failure-in-renamesourcefilebeforetransfer-could-not-find-file"></a>

Two concurrent instances of the same process are racing to acquire the same source file, and the second instance finds it already moved or renamed.

Set "Maximum concurrent instances" to 1 on the trigger to prevent concurrent file access conflicts.

#### Process execution error reported under a different process execution (wrong GUID in logs) <a href="#id-49.-process-execution-error-reported-under-a-different-process-execution-wrong-guid-in-logs" id="id-49.-process-execution-error-reported-under-a-different-process-execution-wrong-guid-in-logs"></a>

A platform-level bug causes non-`ProcessExecutionException` errors to be logged under a newly generated GUID instead of the original process instance ID, making log correlation difficult.

This is a known bug resolved in newer Frends versions. Upgrade to the latest available version.

#### RangeError: Too many properties to enumerate in UI Foreach view <a href="#id-50.-rangeerror-too-many-properties-to-enumerate-in-ui-foreach-view" id="id-50.-rangeerror-too-many-properties-to-enumerate-in-ui-foreach-view"></a>

A task is returning an excessively large data set, causing the Frends UI to time out when attempting to enumerate and display properties in the Foreach view.

Increase the timeout in the HTTP Task Options. Consider filtering or limiting the result set size earlier in the process to reduce the data volume returned.

#### Rehydration failed: Could not find a Hydrated Process with context id '...' <a href="#id-51.-rehydration-failed-could-not-find-a-hydrated-process-with-context-id" id="id-51.-rehydration-failed-could-not-find-a-hydrated-process-with-context-id"></a>

This error uses legacy terminology ("dehydrate/rehydrate") from older Frends versions. The process state could not be resumed from its persisted checkpoint.

Upgrade Frends. In current versions this feature is called "Suspend/Resume" and the related issues have been addressed.

#### Process fails but does not appear in the Dashboard "Failed Processes" widget <a href="#id-52.-process-fails-but-does-not-appear-in-the-dashboard-failed-processes-widget" id="id-52.-process-fails-but-does-not-appear-in-the-dashboard-failed-processes-widget"></a>

The error is caught and handled internally within the process (e.g., in a Catch block), so no unhandled exception is raised to the platform level, and the process ends with an `End` shape rather than a `Throw`.

Use `Throw` shapes to surface errors when they should be treated as failures. This behaviour was also improved in Frends 6.1.2 — upgrade is recommended.

#### Timeout expired. The timeout period elapsed prior to completion (database operations) <a href="#id-53.-timeout-expired.-the-timeout-period-elapsed-prior-to-completion-database-operations" id="id-53.-timeout-expired.-the-timeout-period-elapsed-prior-to-completion-database-operations"></a>

A SQL query or database migration script is running too long and exceeds the command timeout, often occurring on large databases during process instance log cleanup.

Optimize the SQL query. Increase the `CommandTimeout` value. For large log cleanup tasks, use batch deletion instead of single bulk operations.

#### Database is locked (SQLiteException) <a href="#id-54.-database-is-locked-sqliteexception" id="id-54.-database-is-locked-sqliteexception"></a>

The SQLite database file used by the agent is locked by antivirus software scanning it, or a concurrent database transaction has not been released.

Upgrade to Frends 6.0.3 or later, which includes SQLite concurrency optimizations. For production environments, migrate to SQL Server to avoid SQLite limitations entirely.

#### One or more errors occurred (generic wrapper exception) <a href="#id-55.-one-or-more-errors-occurred-generic-wrapper-exception" id="id-55.-one-or-more-errors-occurred-generic-wrapper-exception"></a>

This is a .NET `AggregateException` wrapper indicating that multiple underlying exceptions occurred simultaneously. The generic message provides no direct diagnostic information.

Expand the error in the process instance logs to inspect the inner exception details. The root cause will be described in the innermost exception.

#### After parsing a value an unexpected character was encountered <a href="#id-56.-after-parsing-a-value-an-unexpected-character-was-encountered" id="id-56.-after-parsing-a-value-an-unexpected-character-was-encountered"></a>

The process received malformed JSON or XML as input data, and the parser encountered a character that does not conform to the expected format.

Validate the input data against the expected schema before processing. Fix the source data and reprocess. Add input validation logic to the beginning of the process.

#### Error converting value {null} to type 'System.Int32' <a href="#id-57.-error-converting-value-null-to-type-system.int32" id="id-57.-error-converting-value-null-to-type-system.int32"></a>

A null value is present where the process or a dashboard widget configuration expects an integer. This can also occur in widget configuration fields left empty.

Check process configuration and dashboard widget settings for null or empty values where integers are required. Upgrade Frends if this affects a known UI widget bug.

#### Cannot implicitly convert type 'object' to 'Newtonsoft.Json.Linq.JArray' <a href="#id-58.-cannot-implicitly-convert-type-object-to-newtonsoft.json.linq.jarray" id="id-58.-cannot-implicitly-convert-type-object-to-newtonsoft.json.linq.jarray"></a>

An expression in the process is producing an `object` type, but the subsequent task or expression expects a `JArray`. The C# compiler cannot convert these implicitly.

Add an explicit cast to the expression: `(JArray)#var.yourVariable`.

#### Instance List Timeout — UI times out viewing the process instance list <a href="#id-59.-instance-list-timeout-ui-times-out-viewing-the-process-instance-list" id="id-59.-instance-list-timeout-ui-times-out-viewing-the-process-instance-list"></a>

The process has too many instances with a high number of promoted values configured, causing the database query for the instance list to time out.

Reduce the number of process instances displayed at once. Reduce the number of promoted values on the process. Change the logging level to "Errors only" for high-volume processes.

#### System.DivideByZeroException: Attempted to divide by zero in schedule trigger <a href="#id-60.-system.dividebyzeroexception-attempted-to-divide-by-zero-in-schedule-trigger" id="id-60.-system.dividebyzeroexception-attempted-to-divide-by-zero-in-schedule-trigger"></a>

The schedule trigger's "Repeat" option is enabled but the repeat interval value has been left empty or set to zero, causing a division-by-zero error during trigger initialisation.

Open the trigger settings and set a valid, non-zero value for the repeat interval field.

### &#x20;Frends UI Errors <a href="#frends-ui-errors" id="frends-ui-errors"></a>

#### You are not listed as an allowed user in this tenant. <a href="#id-61.-you-are-not-listed-as-an-allowed-user-in-this-tenant" id="id-61.-you-are-not-listed-as-an-allowed-user-in-this-tenant"></a>

The user was added via the Frends UI's User Management page but was never formally invited via the Frends Portal, so their account is not properly provisioned for the tenant.

The tenant administrator must invite the user through [http://portal.frends.com](http://portal.frends.com/) . Adding a user only in the Frends UI is insufficient for new user provisioning.

#### AADSTS500212: The user's administrator has set an outbound access policy... <a href="#id-62.-aadsts500212-the-users-administrator-has-set-an-outbound-access-policy" id="id-62.-aadsts500212-the-users-administrator-has-set-an-outbound-access-policy"></a>

The user's Azure Active Directory tenant has an outbound cross-tenant access policy that blocks authentication requests to the Frends tenant.

The user's IT Administrator must update the AAD outbound access policy to allow authentication to the Frends tenant's identity provider.

#### Blank page displayed after SSO login <a href="#id-63.-blank-page-displayed-after-sso-login" id="id-63.-blank-page-displayed-after-sso-login"></a>

A deployment issue or stale authentication parameters are preventing the post-login redirect from completing, resulting in a blank page.

Restart the Frends application service. Clear browser cache and cookies. Attempt login in a new incognito/private browser window.

#### AuthenticationFailureException with HTTP 500 during login <a href="#id-64.-authenticationfailureexception-with-http-500-during-login" id="id-64.-authenticationfailureexception-with-http-500-during-login"></a>

The SSO or OpenID Connect configuration is incorrect or misconfigured, or the authentication service needs to be restarted.

Verify the SSO configuration under Administration → User Management → OpenID. Restart the Frends UI service and reattempt login.

#### 401 Unauthorized errors in the dashboard for viewer-role users <a href="#id-65.-401-unauthorized-errors-in-the-dashboard-for-viewer-role-users" id="id-65.-401-unauthorized-errors-in-the-dashboard-for-viewer-role-users"></a>

The authorization rules for certain API controllers are not correctly configured for the viewer role, causing valid viewer sessions to receive 401 responses.

Assign the user the correct role. This has been fixed in later Frends versions — upgrade is recommended.

#### Dashboard Errors widget does not show new errors after being cleared <a href="#id-66.-dashboard-errors-widget-does-not-show-new-errors-after-being-cleared" id="id-66.-dashboard-errors-widget-does-not-show-new-errors-after-being-cleared"></a>

The widget uses ID-based filtering, which means after clearing, new errors with higher IDs are blocked from appearing due to the stored filter state.

This is a known bug. Upgrade Frends — the fix replaces ID-based filtering with date/time-based filtering.

#### Dashboard error link points to the wrong process <a href="#id-67.-dashboard-error-link-points-to-the-wrong-process" id="id-67.-dashboard-error-link-points-to-the-wrong-process"></a>

An incorrect environment ID is embedded in the widget link, causing the link to resolve to a different process than the one that errored.

Ensure the correct environment ID is configured in the widget. Confirm that the process exists in the same version across all environments.

#### Error converting value {null}... clearedNotifications\\\[0].count — cannot clear notifications <a href="#id-68.-error-converting-value-null-...-clearednotifications-0-.count-cannot-clear-notifications" id="id-68.-error-converting-value-null-...-clearednotifications-0-.count-cannot-clear-notifications"></a>

A null value in the notification configuration causes the "clear notifications" action to fail before it can complete.

This is a known bug. Upgrade to a Frends version in which this null handling issue has been resolved.

#### Dashboard widgets lose their position after a page refresh <a href="#id-69.-dashboard-widgets-lose-their-position-after-a-page-refresh" id="id-69.-dashboard-widgets-lose-their-position-after-a-page-refresh"></a>

Widget layout positions are not persisted to the backend, so every page load resets the widget arrangement to its default state.

This is a known bug. Upgrade Frends to a version where dashboard widget positions are persisted.

#### UI not updating; processes cannot be started manually from the UI <a href="#id-70.-ui-not-updating-processes-cannot-be-started-manually-from-the-ui" id="id-70.-ui-not-updating-processes-cannot-be-started-manually-from-the-ui"></a>

The Frends Agent has lost its connection to the Azure Service Bus, preventing status updates and control messages from reaching the UI.

Check the agent logs for Service Bus connection errors. Restart the Frends Agent service. If the problem persists, reboot the agent host machine.

#### Frends UI is down after a database restart and does not recover automatically <a href="#id-71.-frends-ui-is-down-after-a-database-restart-and-does-not-recover-automatically" id="id-71.-frends-ui-is-down-after-a-database-restart-and-does-not-recover-automatically"></a>

The IIS application pool for the Frends UI starts before the database is fully available, causing a failed startup that is not automatically retried.

Restart the IIS service on the Frends UI server. To prevent this in the future, configure the `World Wide Web Publishing Service` (W3SVC) and `Windows Process Activation Service` (WAS) for a delayed start so they start after the database is ready.

#### ArgumentOutOfRangeException: Index and length must refer to a location within the string in API Monitoring <a href="#id-72.-argumentoutofrangeexception-index-and-length-must-refer-to-a-location-within-the-string-in-api-m" id="id-72.-argumentoutofrangeexception-index-and-length-must-refer-to-a-location-within-the-string-in-api-m"></a>

A bug in the API Monitoring view causes a crash when truncating log body content for display, particularly when certain filter combinations are used.

As a workaround, adjust the active filter selection. This issue has been fixed in later Frends versions — upgrade is recommended.

### Authentication & Authorization Errors <a href="#authentication-and-authorization-errors" id="authentication-and-authorization-errors"></a>

#### Error 550 5.7.30 Basic authentication is not supported for Client Submission <a href="#id-73.-error-550-5.7.30-basic-authentication-is-not-supported-for-client-submission" id="id-73.-error-550-5.7.30-basic-authentication-is-not-supported-for-client-submission"></a>

Microsoft Exchange Online has retired SMTP Basic Authentication, so any Frends process or LogService still using username/password over SMTP will fail with this error.

Migrate email sending to OAuth 2.0 (client credentials flow). Alternatively, switch to Microsoft 365 High Volume Email or Azure Communication Services as the sending channel.

#### Access is denied. Check credentials and try again. (Microsoft Graph API email sending) <a href="#id-74.-access-is-denied.-check-credentials-and-try-again.-microsoft-graph-api-email-sending" id="id-74.-access-is-denied.-check-credentials-and-try-again.-microsoft-graph-api-email-sending"></a>

The Azure AD application registration is missing the `Mail.Send` Application permission, or no Application Access Policy has been configured in Exchange Online to allow sending on behalf of the mailbox.

Grant `Mail.Send` as an Application permission (not Delegated) with admin consent in Azure AD. Configure an Application Access Policy in Exchange Online to authorise the app registration for the target mailbox.

#### Error 401 Unauthorized — HTTP request fails when the username contains an umlaut or special character <a href="#id-75.-error-401-unauthorized-http-request-fails-when-the-username-contains-an-umlaut-or-special-charac" id="id-75.-error-401-unauthorized-http-request-fails-when-the-username-contains-an-umlaut-or-special-charac"></a>

A bug in `Frends.Web.Web.HttpRequest` (v1.2.57) causes incorrect encoding of usernames containing special characters such as umlauts, resulting in a failed Basic Auth header.

As a workaround, use a username that does not contain special characters. Report the issue to the Frends task team so it can be addressed in the next task release.

#### Session expired or invalid (Salesforce) <a href="#id-76.-session-expired-or-invalid-salesforce" id="id-76.-session-expired-or-invalid-salesforce"></a>

The Salesforce OAuth session token used by the process has expired, causing subsequent API calls to be rejected.

Re-authenticate to obtain a fresh token. Implement token refresh logic in the process so that a new session is requested automatically when expiry is detected.

#### Error 403 — Make sure the value of Authorization header is formed correctly including the signature (Azure Storage) <a href="#id-77.-error-403-make-sure-the-value-of-authorization-header-is-formed-correctly-including-the-signatur" id="id-77.-error-403-make-sure-the-value-of-authorization-header-is-formed-correctly-including-the-signatur"></a>

The shared access signature or HMAC token for Azure Storage is invalid, most commonly because the server clock on the agent machine is out of sync with Azure's time servers.

Synchronise the agent server's clock via NTP. Verify the token's validity period and confirm that the clock skew does not exceed Azure's accepted tolerance.

#### INVALID\\\_SESSION\\\_ID (Salesforce) <a href="#id-78.-invalid-_session-_id-salesforce" id="id-78.-invalid-_session-_id-salesforce"></a>

The Salesforce session has been invalidated, either because it expired or was explicitly revoked.

Implement automatic session refresh or re-authentication logic in the process so a new session ID is obtained before each API call or when an `INVALID_SESSION_ID` error is detected.

#### Your API licence has expired. Please contact support. <a href="#id-79.-your-api-licence-has-expired.-please-contact-support" id="id-79.-your-api-licence-has-expired.-please-contact-support"></a>

HTTP authentication credentials used to call a third-party API have expired, causing the API to reject the request.

Rotate the expired credentials in the third-party service. Store the new credentials as Frends Environment Variables marked as secrets so they can be updated centrally without changing process logic.

#### Key: 'MWF\\\_Token' does not exist. <a href="#id-80.-key-mwf-_token-does-not-exist" id="id-80.-key-mwf-_token-does-not-exist"></a>

An authentication token expected by the process is either missing from the environment or has expired and was not refreshed before the process attempted to use it.

Implement token generation or refresh logic at the start of the process, or use a scheduled background process to keep the token current. Store the token in a Shared State variable or Environment Variable.

#### Unauthenticated requests to the MCP endpoint are not rejected <a href="#id-81.-unauthenticated-requests-to-the-mcp-endpoint-are-not-rejected" id="id-81.-unauthenticated-requests-to-the-mcp-endpoint-are-not-rejected"></a>

The MCP (Management & Control Plane) endpoint has been left without authentication configured, allowing unauthenticated callers to access it.

Configure Bearer token authentication for the MCP endpoint. Ensure that requests without a valid token receive a `401 Unauthorized` response.

#### License reservation error. License cannot be used, try again. <a href="#id-82.-license-reservation-error.-license-cannot-be-used-try-again" id="id-82.-license-reservation-error.-license-cannot-be-used-try-again"></a>

A VM network adapter issue or licensing conflict is preventing the Frends license from being reserved on the current machine.

Restart the VM. If the error persists after restart, review the VM's network adapter settings, as the license mechanism may depend on a stable MAC address or network identity.

### Trigger Errors <a href="#trigger-errors" id="trigger-errors"></a>

#### File Trigger turns blue then immediately turns red <a href="#id-83.-file-trigger-turns-blue-then-immediately-turns-red" id="id-83.-file-trigger-turns-blue-then-immediately-turns-red"></a>

The Frends Agent service account does not have the necessary read/write permissions on the directory being monitored by the file trigger, causing the trigger to fail immediately after initialisation.

Grant the Frends Agent service account read and write permissions on the target directory. Restart the trigger after applying the permissions.

#### System.IO.IOException: The network path was not found <a href="#id-84.-system.io.ioexception-the-network-path-was-not-found" id="id-84.-system.io.ioexception-the-network-path-was-not-found"></a>

The network share specified in the file trigger configuration is not accessible from the agent server, either because the path is wrong or the share is unavailable.

Verify the UNC path is correct and reachable from the agent machine. Confirm that the credentials configured for the network share are valid and have sufficient access rights.

#### Could not add trigger... will not run in the coming year <a href="#id-85.-could-not-add-trigger...-will-not-run-in-the-coming-year" id="id-85.-could-not-add-trigger...-will-not-run-in-the-coming-year"></a>

The trigger's "Season start date" or "Season end date" is set to a date in the past, making it impossible for the scheduler to find a valid upcoming execution time.

Update the trigger's season dates to use current or future dates. Save and re-activate the trigger.

#### Failure while processing schedule trigger... System.DivideByZeroException <a href="#id-86.-failure-while-processing-schedule-trigger...-system.dividebyzeroexception" id="id-86.-failure-while-processing-schedule-trigger...-system.dividebyzeroexception"></a>

The schedule trigger has the "Repeat" option enabled, but the repeat interval value has been left empty or set to zero, causing a division-by-zero error during trigger processing.

Open the trigger settings and enter a valid, non-zero value for the repeat interval.

#### An invalid HTTP trigger URL disables all HTTP triggers on the agent <a href="#id-87.-an-invalid-http-trigger-url-disables-all-http-triggers-on-the-agent" id="id-87.-an-invalid-http-trigger-url-disables-all-http-triggers-on-the-agent"></a>

When one HTTP trigger has a malformed URL, it causes the agent's entire HTTP listener to fail during initialisation, which prevents all other HTTP triggers on the same agent from activating.

Review all HTTP trigger URLs and correct any invalid configurations. Newer versions of Frends include UI-level validation that prevents invalid URLs from being saved — upgrade is recommended.

#### Access to the path '...' is denied — trigger or task fails after a task update <a href="#id-88.-access-to-the-path-...-is-denied-trigger-or-task-fails-after-a-task-update" id="id-88.-access-to-the-path-...-is-denied-trigger-or-task-fails-after-a-task-update"></a>

The old assembly load context for the process was not fully released after a task update, leaving an older DLL locked on disk.

Restart the Frends Agent after updating tasks. For a long-term fix, upgrade to Frends 6.0.2 or later and migrate all tasks to modern .NET 8-compatible versions.

#### Trigger not activating in a High Availability setup <a href="#id-89.-trigger-not-activating-in-a-high-availability-setup" id="id-89.-trigger-not-activating-in-a-high-availability-setup"></a>

In a multi-agent High Availability setup, triggers require a shared central database to coordinate which agent holds the primary role. Without this, triggers may not activate reliably across agents.

Configure a shared SQL Server database as the central state store for the Agent Group. This enables proper trigger coordination and automatic failover between agents.

### Common Questions About Frends <a href="#common-questions-about-frends" id="common-questions-about-frends"></a>

#### How do I handle errors in a process? <a href="#id-90.-how-do-i-handle-errors-in-a-process" id="id-90.-how-do-i-handle-errors-in-a-process"></a>

Frends offers several layers of error handling depending on how much control is needed. Transient errors can be handled with the built-in "Retry on failure" option available on individual tasks. For structured try-catch logic, a **Scope** shape combined with a **Catch** shape allows errors within a defined block to be caught and handled gracefully. For tenant-wide unhandled exceptions, an **Error Handling Subprocess** can be configured at the environment level to catch anything not handled locally.

#### How do I pass connection strings or secrets to processes? <a href="#id-91.-how-do-i-pass-connection-strings-or-secrets-to-processes" id="id-91.-how-do-i-pass-connection-strings-or-secrets-to-processes"></a>

Use **Environment Variables**, configured under Administration → Environments in the Frends UI. Variables can be defined per environment (e.g., Development, Test, Production) and referenced in process expressions using `#env.VariableName`. Sensitive values such as passwords and API keys should be stored with the **Secret** flag enabled, which encrypts the value at rest and hides it from the UI.

#### How do I achieve High Availability for on-premises agents? <a href="#id-92.-how-do-i-achieve-high-availability-for-on-premises-agents" id="id-92.-how-do-i-achieve-high-availability-for-on-premises-agents"></a>

Install multiple Frends Agents into the same **Agent Group** and configure a shared SQL Server database as the central state store for the group. In this setup, one agent acts as primary and runs stateful triggers (e.g., Schedule, File). If the primary agent becomes unavailable, another agent in the group automatically takes over the primary role, providing failover without manual intervention.

#### Can I test a single task without running the whole process? <a href="#id-94.-can-i-test-a-single-task-without-running-the-whole-process" id="id-94.-can-i-test-a-single-task-without-running-the-whole-process"></a>

Yes. In the Process Editor, select any task shape and use the **Task unit test** feature. You can provide custom input values for that specific task and execute it in isolation to inspect the output and verify its behaviour without triggering the full process flow.

#### Why is a failed process not showing on the Dashboard "Failed Processes" widget? <a href="#id-95.-why-is-a-failed-process-not-showing-on-the-dashboard-failed-processes-widget" id="id-95.-why-is-a-failed-process-not-showing-on-the-dashboard-failed-processes-widget"></a>

The widget only surfaces **unhandled exceptions** — errors that propagate all the way to the platform level. If the process catches the error internally (e.g., in a Catch block) and ends with an `End` shape rather than a `Throw`, the process is not recorded as failed. Use `Throw` shapes to explicitly mark an execution as failed. This behaviour was also improved in Frends 6.1.2.

#### What ports does a Frends Agent need open for outbound traffic? <a href="#id-97.-what-ports-does-a-frends-agent-need-open-for-outbound-traffic" id="id-97.-what-ports-does-a-frends-agent-need-open-for-outbound-traffic"></a>

The agent requires outbound access on the following ports: port **443** to `*.frendsapp.com` and Azure Blob Storage; ports **443, 5671, and 5672** to Azure Service Bus (if 5671/5672 are blocked, use `AmqpWebSockets` on 443); port **1433** to SQL Server; and port **5432** to PostgreSQL. All outbound, no inbound ports are required for basic agent operation.

#### How do I limit a process to one concurrent instance? <a href="#id-98.-how-do-i-limit-a-process-to-one-concurrent-instance" id="id-98.-how-do-i-limit-a-process-to-one-concurrent-instance"></a>

In the process trigger settings, set **"Maximum concurrent instances"** to `1`. This ensures that only one instance of the process runs at a time, which is essential for file-based processes where concurrent instances could race to acquire the same files and cause data inconsistencies.

#### What log level should I use in production? <a href="#id-99.-what-log-level-should-i-use-in-production" id="id-99.-what-log-level-should-i-use-in-production"></a>

**"Only errors"** is the recommended log level for high-volume production processes, as it significantly reduces the volume of data written to the log database and prevents performance degradation. To capture specific business-relevant data regardless of log level, use **Promoted Values** — these are always logged independently of the selected log level.

#### Why do process instances not appear in logs even though the process ran? <a href="#id-100.-why-do-process-instances-not-appear-in-logs-even-though-the-process-ran" id="id-100.-why-do-process-instances-not-appear-in-logs-even-though-the-process-ran"></a>

If the log level is set to **"Only errors"**, successful process executions are intentionally suppressed and will not appear in the instance list. Additionally, if the agent is offline or cannot write to the log database, entries may be lost. Verify the log level setting on the process and confirm the agent is connected and able to reach the log database.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.frends.com/guides/general/common-errors-and-faq.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.