Connector Troubleshooting

Connectors bridge Saltare with external services. When they break, it's usually an authentication issue, a webhook configuration problem, or a missing permission. This guide helps you diagnose and fix common connector issues.

OAuth Flow Fails

"Authentication failed" or Redirect Error

When clicking "Install" for a GitHub, Google, GitLab, or Discord connector and the OAuth flow fails:

Check the redirect URL. The external service must have Saltare's callback URL registered as an authorized redirect. This is usually configured automatically, but may need manual setup for self-hosted instances.

Check permissions. Ensure you're granting all requested permissions during the OAuth flow. Some services let you selectively deny permissions, which can break the connector.

Try again. OAuth tokens are time-sensitive. If you waited too long on the authorization page, the flow may have expired. Start the install process again.

Clear browser cookies. Occasionally, stale session cookies from the external service interfere. Try in a private/incognito window.

Connector Deactivated

If you receive a "Connector deactivated" notification, the connection to the external service has been lost. Common causes:

Expired Token

OAuth tokens have expiry periods. Some services (like GitHub) issue long-lived tokens, while others (like Google) require periodic re-authentication.

Fix: Go to Settings > Connectors, find the deactivated connector, and click "Re-authenticate" to start a fresh OAuth flow.

Revoked Access

If someone revoked Saltare's access from the external service's settings (e.g., GitHub > Settings > Applications), the connector loses its token.

Fix: Re-install the connector from Settings > Connectors.

API Key Changed

For API-type connectors (web search, news API), if the API key was rotated or revoked externally, the connector stops working.

Fix: Update the API key in the connector's settings.

Webhooks Not Receiving Events

Check the Webhook URL

Copy the webhook URL from Settings > Connectors and verify it's correctly pasted in the external service's webhook configuration. Common mistakes:
- Missing the /hooks/ prefix
- Extra whitespace in the URL
- Using HTTP instead of HTTPS

Check HMAC Validation

If you configured a webhook secret for HMAC-SHA256 validation, ensure the same secret is set in both Saltare and the external service. Mismatched secrets cause all payloads to be silently rejected.

Firewall or Network Issues

If your external service sends webhooks from specific IP ranges, ensure those IPs can reach your Saltare instance. This is more relevant for self-hosted deployments.

Test with a Simple Event

Trigger a simple event in the external service (e.g., create a test issue in GitHub) and check if it appears in Saltare. If nothing happens:
1. Check the connector's status in Settings > Connectors
2. Verify the webhook URL is correct
3. Check if the connector's trigger skill is enabled and attached to an agent

Service-Specific Issues

GitHub

• "Not installed" error: The GitHub App needs to be installed on the repository or organization. Go through the installation flow again and ensure you select the correct repos.
• Missing repositories: If you added new repos after initial setup, you may need to update the GitHub App's repository access in GitHub settings.

Google (Calendar, Drive)

• "Access denied" on re-auth: Google sometimes requires you to remove and re-grant access. Go to myaccount.google.com > Security > Third-party apps, remove Saltare, then re-install the connector.
• Wrong account: If you have multiple Google accounts, make sure you're authenticating with the correct one during the OAuth flow.

Slack

• Bot not in channel: The Slack bot must be invited to channels before it can read or post messages. Use /invite @Saltare in the Slack channel.
• Missing scopes: If you see permission errors, the Slack app may need additional OAuth scopes. Re-install the connector to request updated permissions.

Discord

• Bot offline: Ensure the Discord bot is online and has the correct permissions in the server settings.
• Missing channel access: The bot needs explicit access to channels in Discord's permission system.

Testing Connectivity

After fixing a connector issue:
1. Go to the connector's detail page in Settings > Connectors
2. Try a simple operation (e.g., ask an agent to list GitHub issues)
3. If it works, the connector is healthy

Still Stuck?

• Check the Setting Up Connectors guide for step-by-step setup instructions
• Verify your workspace plan supports connectors (Pro plan required)
• For webhook issues, check your external service's webhook delivery logs for error details