How to troubleshoot connector actions
Use this topic when a connector action fails in a playbook run, returns unexpected data, or worked previously and now fails after a configuration or connector update. Follow these steps to validate the asset, test the action, read error details, confirm connector version, rule out TLS issues, and compare results to the third-party API.
Choose your path
Goal | Where to go |
|---|---|
Confirm credentials and endpoint before running playbooks | Test connector assets — Test Connection |
Debug one action with sample inputs | Discovered Outputs and Testing — Test tab on the action |
Debug a full playbook test run | Test Console — Runs tab |
Check whether a newer connector is available | Library / ORCHESTRATION > Connectors |
Connector-specific auth and parameters | Connector configuration on docs.swimlane.com/connectors (search by connector name) |
Follow the full troubleshooting sequence | Continue with this topic |
Prerequisites
Requirement | Details |
|---|---|
Permissions | Ability to edit the playbook and the connector asset used by the failing action. To use Test Connection, your role may need Assets → Test (see Test connector assets). |
Asset | A connector-backed asset (not a custom key asset) selected on the failing action. |
Vendor access | For advanced checks, ability to call the vendor API from Postman or curl using the vendor’s documentation (same network path as production, if possible). |
Overview: where failures usually occur
Connector actions call an external system through Swimlane Turbine. A failure is usually in one of these areas:
Area | What you might see |
|---|---|
Asset configuration | Test Connection fails; wrong URL, token, or OAuth settings |
Action inputs | Test action fails with validation or HTTP 400 from the vendor |
Third-party API | Error status codes and messages in action Error outputs |
Connector version | Behavior changed after an update; Update available on the connector |
TLS / SSL | Certificate or handshake errors (common with private CAs or TLS inspection) |
Playbook orchestration | Run cancelled, timeout, or failure before the connector step runs |
Start with the asset and a single action test before reviewing an entire playbook run.
Step 1 — Validate the connector asset
Connection testing checks credentials, base URL, and related asset parameters without running the full playbook.
- Navigate to ORCHESTRATION > Assets.
- Open the asset used by the failing action in Edit Asset mode.
- On the Configuration tab, review parameters (URL, tokens, OAuth, proxy settings if applicable).
- Click Test Connection.
- Wait for the result.
Result | Next step |
|---|---|
Test was successful | Continue to Step 2 — Test the connector action. |
Test was failed | On the History tab, open View in Details for the failed test and note the diagnostic message. Fix asset configuration or see Common symptoms. |
Note: Test Connection is not available for all asset types. Custom assets do not support connection testing. Some connectors require a supported test action in the connector manifest. See Test connector assets — When a connector does not support testing.
Connection testing is different from View & Test on the asset Usage tab: Usage runs a specific playbook action; Configuration Test Connection validates the asset only.
Step 2 — Test the connector action
Testing one action isolates playbook logic from a single API call.
- Open the playbook in the canvas.
- Select the failing connector action and click Configure.
- Open the Test tab.
- Enter test inputs (or use From Previous Run if available).
- Confirm the correct asset is selected on the action.
- Click Test.
- Review the Result pane and the Discovered Outputs tab.
Read error details
HTTP native actions, script actions, and connectors expose a base Error output when a test or run fails. Use it to see status codes and messages from the vendor or connector.
Example expressions (replace MyConnectorAction with your action name):
$actions.MyConnectorAction.result.error.errorMessage
$actions.MyConnectorAction.result.error.statusCodeFor more examples, see Discovered Outputs and Testing — Error outputs.
Test result | Next step |
|---|---|
Test succeeds, run fails | Compare test inputs vs production inputs (Step 6). Review the failed playbook run (Step 3). |
Test fails with auth errors (401/403) | Fix asset credentials; confirm permissions in the vendor admin console and in the connector doc on docs.swimlane.com. |
Test fails with TLS/certificate errors | See Step 5 — TLS and SSL. |
Step 3 — Review the playbook run
When the failure appears only during a full run:
- Open the playbook and start or locate the run (Test Console or production runs, depending on your workflow).
- Open the Runs tab (Test Console) or the run details view for the failed execution.
- Expand the step with Fail status.
- Copy the Message, Error, and any nested JSON shown for that step.
- Note the run ID and time (UTC if sharing with Support).
To re-test with the same data, use Run again on a previous test run. See Test Console — Re-running tests.
Step 4 — Confirm connector version and updates
A recent connector publish can change inputs, defaults, or API behavior.
- Navigate to ORCHESTRATION > Connectors (or open Swimlane Content / Library from the admin experience your tenant uses).
- Locate the connector by name.
- Note the installed version.
- If Update available appears, open the connector in Swimlane Content and review release notes before updating.
- Compare with the connector’s configuration article on docs.swimlane.com (https://docs.swimlane.com/connectors/<connector-slug>).
After updating a connector, if playbook runs behave unexpectedly, remove old connector actions from the canvas and add the action again from the updated connector so the action definition matches the new version. See Connectors — update available.
Situation | What to do |
|---|---|
Update available; issue started after upgrade | Review release notes; retest Test Connection and action Test; refresh actions on the canvas. |
No update; issue started without connector change | Focus on asset credentials, vendor outage, or input mapping (Steps 1–2 and 6). |
Unsure which version is installed | Record version from Connectors and include it when contacting Support. |
Step 5 — TLS and SSL
Certificate problems often appear as handshake failures, UNABLE_TO_VERIFY_LEAF_SIGNATURE, expired certificate messages, or errors mentioning self-signed certificates.
Connector assets
- Confirm the asset base URL uses the correct scheme (https vs http) and hostname.
- Run Test Connection (Step 1).
- If your organization uses a private CA or TLS inspection, work with your network team so Turbine can trust the certificate chain presented to the connector (your deployment documentation or Support can advise for your hosting model).
HTTP Request native actions
If you use an HTTP Request action (not a marketplace connector) against the same API:
- Open the action Configure panel.
- Open request Settings.
- Review Verify SSL (certificate verification). It is on by default.
Use Verify SSL off only as a temporary test to confirm a certificate-trust issue—not as a permanent production setting.
Step 6 — Compare test inputs and production behavior
Action Test uses the inputs on the Test tab. A playbook run uses live trigger data, variables, and expressions.
Check | Why it matters |
|---|---|
Required fields empty in the run | Vendor returns 400-series errors that look like connector failures |
Wrong asset (staging vs production) | Same action title but different credentials |
Expressions and JSONata | Typo or null reference changes the payload sent to the vendor |
Timeouts | Large responses or slow vendor APIs may timeout in Swimlane while a manual Postman call succeeds with a longer wait |
Re-run the action test with inputs copied from the failed run when possible.
Step 7 — Validate the third-party API (Postman or curl)
This step shows whether the vendor accepts the same request outside Swimlane.
- From the failed action test or run output, note HTTP method, path, headers (excluding secrets), and body structure.
- Open the vendor’s official API documentation (not only the Swimlane connector page).
- In Postman or curl, send the equivalent request using the same credentials as the asset.
- Compare status code and response body to the action Error output.
Postman / curl | Swimlane action | Likely conclusion |
|---|---|---|
Fails | Fails | Credentials, vendor issue, or incorrect request for the API |
Succeeds | Fails | Asset mapping, action inputs, connector version, or Swimlane configuration—gather run ID and open a Support ticket |
Succeeds | Succeeds | Intermittent or data-specific—capture a failing run ID and timestamp |
Common symptoms and fixes
Symptom | Things to try |
|---|---|
401 Unauthorized / 403 Forbidden | Rotate and re-enter token; confirm API roles/scopes in vendor console; read Troubleshooting tips on the connector’s docs.swimlane.com page |
Certificate or SSL errors | Step 5; confirm corporate proxy or TLS inspection |
Test Connection succeeds, action fails | Wrong action inputs; missing path/query parameters; Step 6 |
Update available on connector | Step 4; refresh actions on canvas after update |
Timeout | Reduce payload size; split work across actions; confirm vendor SLA |
429 / rate limit | Slow playbook; add delay; reduce parallel runs |
Test Connection disabled | Connector may not support testing—use action Test tab instead; see Test connector assets |
When to contact Swimlane Support
Open a ticket when Steps 1–7 point to a platform issue, or when you need help after ruling out asset and vendor causes.
Include:
Item | Example |
|---|---|
Tenant URL / region | https://us1.swimlane.app (or your vanity URL) |
Playbook name | |
Run ID | UUID from the failed run |
Connector name and version | From ORCHESTRATION > Connectors |
Asset name | Used on the failing action |
Action name | As shown on the canvas |
Error text | From run details or $actions...result.error |
Timestamps | When the failure occurred (include timezone) |
Postman retest | Same request succeeds / fails outside Swimlane (no secrets in attachments) |
Attach screenshots of the failed run step and action test Error output with sensitive fields redacted.
See also
- Connector catalog: https://docs.swimlane.com/connectors/ (search for your integration)