🔧 EasyTask Integration Server Troubleshooting¶
This guide helps you diagnose and resolve common issues with the EasyTask Integration Server and the Integrations page in the web UI.
🐛 Common Issues and Solutions¶
| # | Issue | Possible Cause | Solution |
|---|---|---|---|
| 1 | Server fails to start | Required port is already in use or configuration error | Check the server logs for specific error messages. Verify the configuration has no syntax errors and all required fields are present. |
| 2 | Server cannot connect to the platform | Platform services not reachable | Verify network connectivity between the Integration Server and the EasyTask platform. Check firewall rules and DNS resolution. |
| 3 | Integration requests timing out | Network or firewall issues | Ensure the Integration Server can reach external services. Check firewall rules and DNS resolution. |
| 4 | Health check not reporting | Server not running or disconnected | Verify the Integration Server is running. Check server logs for connectivity errors. |
| 5 | SSL/TLS certificate errors | Expired or invalid certificates | Renew or update the certificates. Verify the certificate paths in the configuration are correct. |
| 6 | "Test Connection" fails on web UI | Required credentials missing or invalid | Ensure all required fields in the integration form are filled in. Check that the credential values are correct for the target service. |
| 7 | Credential save fails | Secure storage unavailable | Verify the secure storage service is running and accessible. Contact your administrator or EasyTask support. |
| 8 | Integration shows as locked | Sandbox mode restriction | Some integrations require a subscription upgrade. Contact EasyTask support to unlock additional integrations. |
| 9 | Integration form shows no fields | Integration schema not loaded | Contact your administrator to ensure integration schemas are properly configured. |
📋 Checking Integration Server Logs¶
Logs are your primary tool for diagnosing issues.
Accessing Logs¶
- On-Prem: Use the system service manager to view server logs on the infrastructure host.
- Cloud: Use the system service manager on the agent host to view server logs.
- Sandbox: Contact EasyTask support for log access.
Web UI Diagnostics¶
Use the web UI to diagnose integration issues:
| Action | Where | What to Check |
|---|---|---|
| Verify credentials | Integrations page (/integrations) → Select integration → "Test Connection" |
Confirms all required credential fields are filled correctly |
| Check key status | Integrations page → Select integration | Look for key count badge — gray "0 keys" means no credential keys configured |
| Check locked status | Integrations page | Locked integrations show a lock icon with "Unlock this integration with a subscription" |
| Review form errors | Add/Edit Key dialog | Red error messages appear below invalid fields |
| Check alert configuration | Tasks page → Edit task → Alert tab | Amber warning if no credential keys configured for the selected integration |
Common Error Messages¶
| Error Message | Where You See It | Meaning | Action |
|---|---|---|---|
| Missing required fields | Test Connection toast | Required form fields are empty | Fill in all required fields and retry |
| Failed to save credentials | Save Key toast | Credential storage is unavailable | Verify storage connectivity. Contact administrator. |
| Storage not configured | Any key operation | Credential storage is not set up | Contact your administrator or EasyTask support |
| Integration schema not found | Integration detail page | Integration is registered but schema is missing | Contact your administrator |
| Integration not available in sandbox mode | Any operation on locked integration | Sandbox mode restricts access | Contact EasyTask support to upgrade |
| Key name is required | Create Key dialog | No key name entered | Enter a unique name for the key |
| No credentials configured for integration | Task Alert tab | No credential keys configured | Go to Integrations page and create a key for that integration first |
🔄 Restart Procedures¶
Standard Restart¶
- On-Prem: Use the system service manager to restart the Integration Server on the infrastructure host.
- Cloud: Use the system service manager on the agent host to restart the Integration Server.
- Sandbox: Contact EasyTask support.
Verify Restart Success¶
After restarting, confirm the server is healthy: - Check the Integrations page in the web UI to verify connectivity. - If keys were previously configured, try a "Test Connection" to confirm the server is responding.
🔍 Diagnostic Checklist¶
When troubleshooting, follow this checklist:
- Check server status: Verify the Integration Server is running via the system service manager.
- Check recent logs: Review the server logs for error messages.
- Verify platform connectivity: Ensure the Integration Server can reach the EasyTask platform.
- Verify external connectivity: Test DNS and port reachability to the external services you are integrating with.
- Check resource usage: Monitor CPU and memory usage on the host.
- Review configuration: Ensure all required settings are present and valid.
- Check disk space: Insufficient disk space can cause failures.
- Test from web UI: Use the "Test Connection" button on the Integrations page to validate credentials.
- Check key count: Verify that credential keys are configured for the integration (green badge on the Integrations page).
Frequently Asked Questions¶
Q: The Integration Server starts but immediately exits. What should I check? A: Check the server logs for error messages. The most common cause is a configuration error or the platform services being unreachable. Verify all connection settings and ensure the required services are running.
Q: How do I know if the Integration Server is healthy? A: Check the Integrations page in the web UI — if you can see integration types and manage keys, the server is responding. You can also use the "Test Connection" button on a configured integration to verify end-to-end connectivity.
Q: Integration requests are returning errors. How do I debug them? A: First, check the Integration Server logs for detailed error messages. Verify that the target external service is reachable from the Integration Server host. Check credentials and endpoint URLs on the Integrations page. Ensure all required fields are filled in the key configuration.
Q: "Test Connection" shows success but the integration still fails when tasks run. What's wrong? A: The "Test Connection" button validates that all required credential fields are filled correctly. It does not test actual network connectivity to the external service. Verify that the Integration Server host can reach the external service, and that the credentials are correct for the production environment.
Q: An integration shows a lock icon and I cannot access it. What should I do? A: Locked integrations indicate a subscription restriction in sandbox mode. Contact EasyTask support to upgrade your subscription and unlock additional integrations.
Q: I see a "No credentials configured" warning when configuring task alerts. What does this mean? A: This means no credential keys have been created for the selected integration. Navigate to the Integrations page, select the integration, and click "Add Key" to create a credential set first.