Troubleshooting Connections & Operations
Troubleshooting Connections & Operations
Even well-configured integrations can run into issues, whether it’s a misconfigured endpoint, expired credentials, or network restrictions. This guide outlines common problems and practical steps to diagnose and resolve issues with Connections and Operations in the Kinetic Platform.
Step 1: Validate the Connection
Before testing an operation, make sure the Connection itself is valid.
Things to Check:
- Base URL: Ensure there are no typos and it includes the proper protocol (
https://). - Authentication Settings: Double-check tokens, credentials, or OAuth configurations.
- Headers: Confirm required headers (e.g.,
Content-Type,Authorization) are correctly added. - SQL Details (if applicable):
- Host, port, and database name
- Username and password
- Secure access via the Kinetic Agent, if needed
Try:
- Editing the connection and saving it again to force a config refresh
- Testing from another tool (e.g., Postman, DBeaver) using the same credentials and endpoint
Step 2: Test the Operation
Use the Test Operation feature in the platform UI to preview the result of an operation without needing to run a full workflow.
When testing, look for:
- Request URL & Payload (HTTP): Are the inputs correctly mapped?
- SQL Parameters: Are required inputs present and in the correct format?
- Error Messages: Review returned errors or stack traces for missing variables or malformed queries.
Tip: Use sample test values that resemble real submissions or records.
Step 3: Check Data Mappings
If your operation is working in test mode but failing in a workflow, the issue may be with input mapping.
Check:
- Are the expected values being passed in from the form or workflow node?
- Are field names matching exactly (case-sensitive)?
- Are required parameters missing, null, or in an unexpected format?
Step 4: Review Agent Connectivity (for SQL or On-Prem)
If your connection relies on the Kinetic Agent, ensure:
- The Agent is running and connected
- It’s properly registered to the right Space
- The host system allows outbound traffic to the required target
- No firewall or DNS restrictions are blocking traffic
Check Agent logs for errors and restart the Agent service if needed.
Common Issues & Fixes
| Issue | Possible Cause | Suggested Fix |
|---|---|---|
401 Unauthorized | Missing or invalid credentials | Recheck token, password, or authentication method |
404 Not Found | Incorrect endpoint or path | Verify the endpoint URL and base path |
500 Internal Server Error | Remote system issue or malformed payload | Inspect the payload and try manually from Postman |
Request Timed Out | Network or DNS issue | Check network, Agent status, or endpoint health |
Empty Response | Query returned no data | Confirm expected data exists for given inputs |
| SQL Operation Fails | Parameter mismatch or bad syntax | Log actual query inputs and verify SQL syntax |
Still Stuck?
If you're unable to resolve the issue:
- Confirm whether the issue is Connection-related (e.g., cannot reach the external system) or Operation-related (e.g., logic or data issue)
- Reproduce the issue with minimal inputs
- Gather the following before escalating:
- Connection and operation name
- Test inputs used
- Error message or full logs
- Expected behavior
Related Topics
Updated 4 months ago