Skip to main content

Troubleshooting

This guide is organized by symptom. Find the problem you are seeing and follow the fix.

Quick Diagnosis Flow​

When a job fails, follow this path to find the root cause:

Open Failed Run
Go to the execution history and find the failed run
Find First Failed Step
Scroll to the step with FAILED status
Read Error Message
The step error tells you what went wrong
Check Previous Step
Verify the previous step produced the expected output
Apply Fix
Correct the configuration or connection and re-run
Always start with the first failed step. Later failures are often caused by the first one.

Connection Problems​

Most connection issues are between Automation Hub and the external system your step is trying to reach.

SymptomLikely causeWhat to check
Connection timeoutThe external system is not reachableVerify the host and port are correct. Check firewall rules and VPN connection. Try reaching the host from the same network.
Authentication failedCredentials are wrong or expiredCheck the username and password or API key. For OAuth connections, check if the token has expired and needs a refresh.
SSL/TLS errorCertificate issueVerify the certificate is valid and not expired. For testing, try disabling SSL verification on the connection. Check if the system uses a self-signed certificate that needs to be trusted.
Connection refusedThe service is not runningConfirm the service is up and the URL is correct. Check if the port number matches the running service.
DNS resolution failedHostname cannot be foundCheck the hostname for typos. Verify DNS is working from the server. Check if the hostname requires VPN or internal DNS.

General connection tips:

  • Test the connection independently before using it in an automation. Most connection types have a "Test Connection" option.
  • If a connection worked before and stopped, check if credentials were rotated or the external system had maintenance.
  • For cloud services, check the service status page for outages.

Step Execution Problems​

These problems happen when the step starts but cannot complete its work.

Step fails immediately​

The step configuration is likely wrong.

  • Check that all required fields are filled in
  • Verify the action type is correct for what you want to do
  • Make sure the connection assigned to the step is the right one
  • Look at the error message for the specific field or setting that is wrong

Step fails after waiting​

The step ran but hit a timeout or the external system was too slow.

  • Check if the external system is under heavy load
  • For database queries, check if the query is too broad or missing an index
  • Increase the step timeout if the operation legitimately takes a long time
  • Consider breaking large operations into smaller batches

Step succeeds but output is empty​

The step ran correctly but found no data.

  • Check the query or filter criteria in the step configuration
  • Verify the data source actually contains matching records
  • Look for case sensitivity issues in search terms
  • Check date ranges or other filters that may be too restrictive

Step succeeds but output is wrong​

The step returned data, but it is not what you expected.

  • Check field mappings to make sure source and target fields are correct
  • Verify expression syntax in any data transformation
  • Look at the raw output from the previous step to confirm the input data is correct
  • Check if the external system returns data in a different format than expected

Step hangs indefinitely​

The step never completes.

  • Check if a timeout is configured on the step. Steps without timeouts can wait forever.
  • Verify the external system is responding. It may have accepted the request but never sent a response.
  • Check for deadlocks if the step involves database operations
  • Review whether the step is waiting for a callback that will never arrive

Expression Problems​

Expressions reference data from previous steps using step IDs and field paths.

Expression returns empty or null​

  • Verify the step ID in the expression matches the actual step ID (check spelling and case)
  • Confirm the referenced step ran successfully and produced output
  • Check if the field path is correct by examining the actual output of the referenced step
  • Make sure the referenced step runs before the current step in the execution order

Expression returns wrong type​

  • Numbers and strings can behave differently in comparisons and conditions
  • If you need a number but get a string, use JavaScript type conversion in your expression
  • Array fields need indexing (e.g., items[0].name) to get individual elements
  • Nested objects need the full dot-notation path

Expression syntax error​

  • Check that curly braces are balanced and properly nested
  • Verify field path spelling against the actual step output
  • Make sure you are using the correct expression syntax for the step type
  • Look for missing dots between object path segments

Trigger Problems​

Scheduled job did not run​

  • Verify the schedule configuration is correct (cron expression or interval)
  • Check the timezone setting. A job scheduled for 9 AM in UTC runs at different local times.
  • Confirm the job is enabled. Disabled jobs do not run on schedule.
  • Look at the execution history to see if the job ran at an unexpected time

Webhook did not start the job​

  • Verify the webhook URL is correct and accessible from the calling system
  • Check that the HTTP method matches (POST, GET, etc.)
  • Look for rate limiting if many requests arrive at once
  • Check the payload size. Very large payloads may be rejected.
  • Verify that the webhook is enabled on the job

Webhook started but data is missing​

  • Check that the field names in trigger.payload match the keys in the incoming request body
  • Verify the content type header matches the payload format (e.g., application/json for JSON)
  • Look at the raw trigger context in the execution to see what data actually arrived
  • Check if the sending system is including all expected fields

Performance Problems​

Job takes longer than expected​

  • Open the execution and check the duration of each step to find the slow one
  • Database queries are often the slowest part. Check if the query can be optimized.
  • API calls to slow external systems can be improved with caching or batching
  • Consider using test mode to pin slow steps during development

Loop runs too long​

  • Check how many items the loop is processing. A loop over thousands of items will take a long time.
  • Consider filtering the input data before the loop to reduce the number of iterations
  • Batch operations instead of processing one item at a time
  • Set a reasonable limit on the number of iterations

Multiple jobs competing for resources​

  • Check concurrency settings to limit how many runs execute at the same time
  • Stagger scheduled jobs so they do not all start at the same minute
  • Monitor resource usage during peak times to identify bottlenecks

Approval Problems​

Approver never received the email​

  • Verify the approver's email address is correct in the step configuration
  • Check the approver's spam or junk folder
  • Confirm that platform email sending is configured correctly
  • Try sending a test email to the same address from another step to isolate the issue
  • The approval link may have expired. Check the timeout setting on the approval step.
  • The link may have already been used. Each approval link can only be used once.
  • Verify the callback URL is accessible from the approver's network. Internal URLs may not work for external approvers.

Approval timed out​

  • Increase the timeout duration if approvers need more time
  • Set up a reminder or escalation so the approver does not forget
  • Check if the approver was available during the approval window
  • Consider adding a fallback approver for time-sensitive workflows

Common Error Messages​

Error messageWhat it meansWhat to do
Connection timed outThe external system did not respond in timeCheck network connectivity, firewall rules, and VPN. Verify the host and port are correct.
401 UnauthorizedCredentials are wrong or expiredUpdate the connection with valid credentials. For OAuth, refresh the token.
404 Not FoundThe URL or resource path does not existCheck the URL for typos. Verify the resource still exists in the external system.
429 Too Many RequestsThe external system is rate limiting your requestsAdd a delay between requests. Configure retry strategies with backoff. Reduce the frequency of the automation.
500 Internal Server ErrorThe external system had an internal errorThis is not your fault. Retry the operation. If it persists, contact the external system owner.
No handler found for action typeThe plugin for this step type is not loaded or the action name is wrongCheck that the action type in the step configuration is spelled correctly. Verify the plugin is installed and loaded.

Getting More Information​

When the error message alone is not enough, use these techniques to dig deeper.

Enable debug logging. Detailed step execution messages can reveal exactly where the step failed and what data it was working with. See logging for how to configure log levels.

Check execution history for patterns. If a job fails intermittently, look at the last several runs to see if there is a pattern. Failures at the same time of day may indicate load issues. Failures on specific days may indicate scheduled maintenance on the external system.

Compare with a recent successful run. Open a run that worked and a run that failed side by side. Compare the input data, step configurations, and connection settings to spot differences.

Review the trigger context. For triggered jobs, check the trigger context in the execution details. Unexpected input data from the trigger can cause steps to fail in ways that are not obvious from the error message alone.