Troubleshooting workflows

Issue

Rate limit exceeded error occurs when you send too many requests within a short period of time, exceeding the maximum number of requests allowed by a service or API.

Resolution

Follow these steps to avoid exceeding the rate limit:

1. Reduce request frequency by avoiding unnecessary or duplicate API calls.

2. Retry failed requests after a short wait. If the retry fails, gradually increase the wait time between retries instead of retrying immediately.

3. Limit multiple requests by queuing them instead of sending them all at once.

Issue

The tenant has reached the request limit error, which results in a slow down or a 429 error.

Cause

This occurs when the number of workflow executions exceeds the allowed request threshold within a given time frame for your Nintex Workflow tenant. Throttling is a common mechanism in cloud-based platforms used to ensure fair use and resource availability across all tenants. When a resource (like workflow execution) is requested too frequently within a short period, the system will either slow down or reject additional requests, typically with a 429 (Too Many Requests) error. In many cases, this can be triggered by high-volume workflow activity, especially when workflows are triggered in rapid succession or in bulk. Nintex Workflow tenants have a Workflow Start threshold of 10,000/hour per tenant.

Possible error messages

Due to a high volume of workflow executions in this Nintex Workflow tenant, this test could not be started. Please try again later.

HTTP/1.1 429 Too Many Requests "message":"[WorkflowStart.RateLimited] Tenant has reached the request limit", "code":"TOO.MANY.REQUESTS", "correlationId":"nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnn"

Resolution

Follow these steps to avoid exceeding the rate limit:

• Optimize request operations:

  • Add more granular conditions for a request to start workflows.

  • Fewer requests per hour.

  • Stagger requests throughout the day.

  • Reduce the frequency of requests.

• For a better understanding of what could cause throttling see Workflow limits

Issue

The function host is unavailable, which stops the system from initializing and executing functions. As a result, triggers and incoming requests cannot be processed.

Resolution

Follow these steps to identify the reason that the host fails:

1. Go to your project directory and start function host manually. If the startup fails, review the log output, which indicates the specific reason for the failure.

2. Ensure all local prerequisites, such as .NET functions, Node.js functions, or Python functions, are installed correctly. Verify that the installed versions match the function app configuration.

3. Check for port conflicts to ensure no other services are using the same port. Update the port configuration if conflicts are detected.

4. Clean and reinstall project dependencies to ensure that all required files are present and up-to-date.

5. Verify that required configuration files, such as host.json, and local.settings.json, exist and are valid. Confirm that all required configuration values are present.

6. Review function app logs for missing modules, syntax error or configuration issues.

7. Restart or redeploy the function app.

Issue

This error occurs when a workflow tries to communicate with a service or endpoint, but the connection ends before a complete response is received.

Cause

This error occurs due to the following:

• Connection issues or timeouts that cause network interruptions during the call.

• Incomplete or invalid responses received from the service you're connecting to.

• Large data requests by workflow actions that cause execution delays or exceed configured limits.

• Server-side throttling where the service you’re connecting to limits or blocks requests.

Resolution

Follow these steps to resolve the error:

1. Run the workflow again to rule out temporary network issues.

2. Check service endpoint availability for API status, uptime, and server load.

3. Reduce the size of the request if possible.

4. Validate that the endpoint returns valid JSON or XML data.

5. Increase timeout settings, if allowed.

Issue

This error occurs when the workflow attempts to connect to a URL or service, but the hostname cannot be resolved.

Cause

This error occurs due to the following:

• Incorrect URL or hostname.

• Domain Name System (DNS) resolution failure where the domain cannot be found or DNS is temporarily unavailable.

• Service you are connecting to has been moved or retired.

• Network restrictions such as firewall, proxy, or VPN blocking the domain.

Resolution

Follow these steps to resolve the error:

1. Verify the URL or hostname used in the workflow.

2. Ensure the service is active and has not been migrated or retired.

3. Test the endpoint using a browser or command-line tool to verify DNS resolution.

4. Ensure the endpoint is accessible from the Nintex environment.

Issue

This error occurs when a workflow action that calls an HTTP service fails after multiple retry attempts.

Cause

This error occurs due to the following:

• Temporary network connectivity issues.

• Target service is unavailable or slow to respond.

• Request timeouts caused by long-running or large requests.

• Service-side throttling or rate limits.

• Invalid endpoint configuration.

Resolution

Follow these steps to resolve the error:

• Run the workflow again to rule out temporary network issues.

• Verify that the target service or API endpoint is available and responding.

• Reduce the size or complexity of the request.

• Review timeout and retry settings for the HTTP action.

• Ensure the service does not enforce rate limits that block retries.

• Validate the endpoint URL, authentication, and request headers.

Issue

This error occurs when a workflow sends an HTTP request with invalid or unsupported headers. The request fails before the service can process it.

Cause

This error occurs due to the following:

• The header name contains invalid characters or formatting.

• A required header value is missing or empty.

• A header value isn’t in the expected format. For example, Authorization or Content-Type.

• Duplicate or conflicting headers are included.

• A restricted header is manually set and overrides a system-managed header.

Resolution

Follow these steps to resolve the error:

• Review all request headers for valid names and correctly formatted values.

• Remove unnecessary or duplicate headers.

• Ensure required headers, such as Authorization and Content-Type, are present and valid.

• Don’t manually set headers that the system manages automatically.

• Test the request with a tool such as Postman or curl to confirm the headers are accepted.

• Run the workflow again after making updates.

Issue

This error occurs when a workflow attempts to connect to a secure HTTPS endpoint, but the SSL/TLS certificate presented by the remote service can’t be validated. As a result, the connection is blocked and the request fails.

Cause

This error occurs due to the following:

• The remote service uses a self-signed certificate that isn’t trusted.

• The certificate has expired or isn’t valid.

• The certificate hostname doesn’t match the endpoint URL.

• Required intermediate certificates are missing from the certificate chain.

• The service enforces stricter TLS or certificate validation rules.

Resolution

Follow these steps to resolve the error:

• Verify that the endpoint uses a valid and trusted SSL/TLS certificate.

• Confirm the certificate hasn’t expired and is issued by a trusted certificate authority (CA).

• Ensure the hostname in the certificate matches the endpoint URL.

• Check that all required intermediate certificates are correctly installed on the server.

• Avoid using self-signed certificates in production environments.

• Test the endpoint using a tool such as a browser or Postman to confirm the certificate is accepted.

• If the service was recently updated, restart the workflow and try again.

Issue

This error occurs when a workflow attempts to connect to a Nintex service or endpoint, but the connection is refused or terminated before the request headers are processed. The request fails and the workflow can’t continue.
Typical error message: Upstream connect error or disconnect/reset before headers.

Cause

This error occurs due to the following:

• A temporary authentication or session issue for the user.

• An expired or invalid authentication token.

• Cached login session data that causes a conflict.

• Network connectivity or service availability issues.

• Slow service response that causes a connection timeout.

In some cases, the issue affects only a single user rather than all users in the tenant.

Resolution

Follow these steps to resolve the error:

1. Ensure the affected user signs out of Nintex Workflow.

2. Have the user access the tenant directly using the following URL: https://yourNACtenant.workflowcloud.com/otp

3. Sign in again to establish a new authentication session.

4. Access the task or workflow from the tenant after signing in.

5. If the issue persists, wait a few minutes and try again to rule out a temporary service or network issue.

6. Run the workflow again.

If the error continues to occur across multiple users or workflows, contact Nintex Support and include the full error message and timestamp.

Issue

This error occurs when a workflow action that uses the SharePoint Online connector returns a service unavailable error intermittently.

Cause

The connector times out or encounters throttling limits when retrieving data from a SharePoint list. This typically happens when the list is large or the action is configured to return more data than the workflow needs.

Resolution

Follow these steps to resolve the error:

• Limit the number of items the action returns: configure the action to return only the number of items required rather than retrieving the full list.

• Use indexed columns for filtering: ensure that any columns used to filter results are indexed in SharePoint. This reduces the load on the connector when retrieving the list.

• Limit the columns the action returns: configure the action to return only the columns that your workflow requires. Retrieving unnecessary columns increases the size of the response and can contribute to timeouts.

• Reduce the size of the SharePoint list: if the list contains a large number of items, consider archiving older items to reduce the overall list size.

If the error persists, contact Nintex Support.

Issue

Nintex Workflow tasks are not downloaded to Nintex Mobile. The download silently fails and returns no tasks in Nintex Mobile.

Cause

The Nintex Workflow URL used for authentication uses HTTP (Hypertext Transfer Protocol) instead of HTTPS (Hypertext Transfer Protocol Secure).

Resolution

Ensure that your Nintex Workflow URL used for authentication starts with https://.

Issue

The SharePoint connector tried to update a file or list item using an outdated version token and you received this error message:

Received an error response from the connector: BadRequest: Version conflict.

Cause

This error occurs due to the following:

• Multiple instances of Nintex Workflow are trying to update the exact same SharePoint item or file at the exact same time.

• The workflow modified a SharePoint item's properties right after creating it, but instead of fetching the newly updated item token, it used the original "Create" metadata.

• The SharePoint connector passed an outdated header or an obsolete version identifier during a request.

Resolution

Follow these steps to resolve the error:

• Pause the SharePoint action and try running it again.

• If multiple instances of your workflow are running at the same time and targeting the same SharePoint lists, modify them to execute one after another.

• Refresh the SharePoint item properties before updating them so that you are pulling the fresh version of metadata before committing a new change.

Issue

Another workflow or user modified the same SharePoint item, folder, or file at the exact same time your SharePoint action tried to write to it and you received this error message:

Received an error response from the connector: BadRequest: Save conflict.

Cause

• Multiple instances of Nintex Workflow are trying to update the exact same SharePoint item, folder, or file at the exact same time.

• If your SharePoint library requires users to check out files before editing them, or if a required field is missing, saving a file could cause a conflict.

• Overlapping workflows or event receivers while migrating content or using tools like ShareGate could trigger this error.

Resolution

Follow these steps to resolve the error:

• Pause the SharePoint action and try running it again.

• Verify your SharePoint list settings to ensure that Require Check Out is set to No, unless specifically needed, and that there are no strict validation rules triggering simultaneously.

• Temporarily disable workflows or event listeners on the SharePoint destination list.

Issue

When using the SharePoint on-premises Create an item or Update item actions, Nintex Workflow returns the following error:

Received an error response from the connector: BadRequest, ResponseStatus: Completed - {"error":{"code":"-1, Microsoft.SharePoint.SPException","message":{"lang":"en-US","value":"The query to field 'Author/UserName' is not valid."}}}

Cause

New SharePoint installations may use different templates that do not include the UserName, FirstName, and LastName fields in the User Information List. As a result, queries referencing the Author/UserName field fail.

Resolution

Follow these steps to resolve the error:

1. Go to Settings > Site Settings > Users and Permissions > Site permissions.

2. Select the group that you use to create the SharePoint connection in Nintex Workflow.

3. On the People and Groups page, click Settings > List Settings.

4. Click Create column and create the following three columns with the Single line of text column type:

   • UserName

   • FirstName

   • LastName

5. Click OK.

Issue

Newly added SharePoint Online list columns do not immediately appear as start event variables in workflows.

Cause

The SharePoint Online list columns are not refreshed in the Workflow designer after new columns are added to the list.

Resolution

Follow these steps to resolve the error:

1. Access the Workflow designer. For more information, see Access the Workflow designer.

2. To refresh the Workflow designer, press Ctrl+Shift+F5. Multiple refresh attempts may be required.

3. Open the Start event configuration panel. For more information, see Open the Start event configuration panel.

4. Refresh the SharePoint Online connection.

5. To reload the available list columns, click Retrieve lists.

6. To verify that the newly added SharePoint Online list columns are now available as start event variables, click Show variable. For more information, see Show variables.