Skip to main content

Connector Troubleshooting

Last updated on

Connector failures block pipeline execution, and the underlying cause is usually a credential, network, permission, or delegate problem. This topic groups the most common connector issues by symptom, explains the root cause of each, and gives you the commands and checks needed to confirm and resolve it.

Failed connection​

A Failed status on a connector indicates that the most recent connection test did not succeed. The following are the most common root causes and their solutions.

Invalid credentials

The token, password, or key referenced by the connector has expired, was revoked, or was entered incorrectly.

Solution:

  1. Verify that the secret still exists and holds a valid value in Harness Secret Manager.
  2. Test the credential manually, for example, use the token to call the provider's API directly.
  3. If the credential is expired, generate a new token or key and update the Harness secret.
  4. Re-test the connector from the Harness UI.
Network connectivity

The delegate cannot reach the target endpoint because of firewall rules, DNS resolution failures, or proxy configuration issues.

Solution:

  1. Confirm that the delegate resolves the target hostname by running a DNS lookup from the delegate host.
  2. Verify that the target port is open, using telnet or curl from the delegate.
  3. Check the firewall and security group rules for both the delegate and the target service.
  4. If you use a proxy, confirm that the delegate proxy configuration includes the target endpoint.
Insufficient permissions

The credentials are valid but lack the required permissions on the external service, for example, a read-only token used for write operations.

Solution:

  1. Review the error message for the specific permission that is missing.
  2. Check the token scopes or the IAM policy attached to the credential.
  3. Update the permission grants on the external service to include the required access.
  4. For GitHub, confirm that the token holds the required scopes, such as repo and admin:repo_hook.
Delegate issues

The delegate assigned to the connector is offline, unhealthy, or lacks the required network access.

Solution:

  1. Navigate to Account Settings, then select Delegates, and verify that the delegate status is Connected.
  2. Check the delegate pod logs for errors or resource constraints.
  3. Verify that the delegate selector on the connector matches an active delegate.
  4. If no delegate selector is set, confirm that at least one delegate with network access to the target is available.
Timeout issues

Connection timeouts occur when the delegate cannot establish a connection to the target service within the configured timeout window.

CauseSolution
Default timeout too lowIncrease the connection timeout value in the connector or delegate configuration.
High network latencyDeploy a delegate closer to the target service, in the same region or VPC.
Incorrect endpoint URLVerify that the endpoint URL and port are correct. Check for typos in the hostname.
Delegate resource constraintsCheck delegate CPU and memory usage. Scale up the delegate if resources are exhausted.

Pipeline vs test failures​

In some cases, a connector test succeeds in the UI but fails during pipeline execution, or the reverse. This discrepancy occurs for several reasons.

Different delegate

The connection test can use a different delegate than the pipeline execution. If the connector has no delegate selector, any available delegate can be chosen, and one delegate can have network access while another does not.

Solution: Add an explicit delegate selector to the connector so that the same delegate serves both the test and the pipeline execution.

Variable resolution

If the connector configuration uses Harness expressions, for example, <+variable.name>, these resolve at pipeline runtime and can be unavailable during a standalone connection test.

Solution: Avoid runtime expressions in connector configurations. Use static values or secret references instead.

Scope mismatch

The test runs at the connector scope, but the pipeline can sit at a different scope, for example, a Project-level pipeline that references an Account-level connector with an incorrect scope prefix.

Solution: Verify that the connector reference includes the correct scope prefix, for example, account.my_connector or org.my_connector.

Concurrent connection limits

The external service can impose concurrent connection limits. A standalone test succeeds because it opens a single connection, but parallel pipeline stages can exceed the limit.

Solution: Check the rate limits and connection quotas of the external service. Limit pipeline parallelism, or use connection pooling where the provider supports it.

Not found errors​

A Connector not found error during pipeline execution indicates that the referenced connector cannot be resolved.

Common causes and scope prefix reference

Common causes:

  • Deleted or renamed: The connector was deleted, or its identifier changed. Identifiers are immutable, so this happens when a connector is recreated with a different ID.
  • Scope mismatch: The pipeline references a Project-level connector, but the connector exists at the Account or Organization level, or the reverse.
  • Incorrect identifier: A typo in the connector reference in the pipeline YAML.

Scope prefix reference:

ScopeReference format
Account levelaccount.connectorIdentifier
Organization levelorg.connectorIdentifier
Project levelconnectorIdentifier (no prefix)

For more information on connector scope, see Connectors overview.

Rate limiting​

External services such as GitHub and GitLab impose API rate limits that affect connector operations, especially during periods of high pipeline activity.

Symptoms and solutions

Symptoms:

  • HTTP 429 (Too Many Requests) errors in pipeline logs.
  • API rate limit exceeded error messages from GitHub or GitLab.
  • Intermittent connector test failures that resolve after a wait.

Solutions:

  • Use GitHub App authentication: GitHub Apps carry higher rate limits, 5,000 requests per hour per installation, compared with 5,000 per hour per user for personal access tokens. For more information on these limits, see GitHub REST API rate limits.
  • Separate connectors for CI and API: Use different tokens for codebase cloning and API operations to distribute rate limit consumption.
  • Reduce polling frequency: If you use polling-based triggers, increase the polling interval to reduce API calls.
  • Use webhooks instead of polling: Configure webhook-based triggers to remove periodic API polling entirely.

Kubernetes issues​

Kubernetes connector issues are among the most common troubleshooting scenarios, and most trace back to certificates, token expiry, or cluster RBAC.

Certificate validation failure

The delegate cannot validate the Kubernetes API server TLS certificate, which produces an unable to verify the first certificate or certificate signed by unknown authority error.

Solution:

  1. Provide the certificate authority (CA) certificate in the connector configuration, using caCertRef.
  2. Confirm that the CA certificate is in PEM format and includes the full chain.
  3. If the cluster uses a self-signed certificate, add the CA to the delegate trust store.
Service account token expired

Kubernetes service account tokens can expire, especially in clusters with token request projection enabled, which is the default in Kubernetes 1.21 and later.

Solution:

  1. Generate a new service account token and update the Harness secret.
  2. Consider the Inherit from Delegate credential type for automatic token management.
  3. For long-lived tokens, create a non-expiring secret-based token. This is not recommended for production.
RBAC permission denied

The service account lacks the Kubernetes RBAC permissions required for the deployment operations, for example, creating or updating Deployments, Services, and ConfigMaps.

Solution: Create a ClusterRole or Role with the required permissions and bind it to the service account.

harness-rbac.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: harness-deployer
rules:
  - apiGroups: ["", "apps", "extensions", "batch"]
    resources:
      - pods
      - services
      - deployments
      - replicasets
      - statefulsets
      - daemonsets
      - jobs
      - configmaps
      - secrets
      - namespaces
      - events
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["networking.k8s.io"]
    resources: ["ingresses"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: harness-deployer-binding
subjects:
  - kind: ServiceAccount
    name: harness-deployer
    namespace: harness-delegate
roleRef:
  kind: ClusterRole
  name: harness-deployer
  apiGroup: rbac.authorization.k8s.io

Cloud authentication failures​

Cloud provider connectors fail most often because of trust policy, region, or project scoping problems rather than invalid credentials. Use the following entries to isolate the cause by provider.

AWS: IAM trust policy

When you use Inherit from Delegate with cross-account access, the trust policy of the target role must allow the delegate instance profile or IRSA role to assume it.

Solution: Verify that the trust policy includes the delegate IAM role ARN in the Principal field, and that the external ID matches.

AWS: STS regional endpoint

Security Token Service (STS) assume-role calls fail when the delegate sits in a different region than the STS endpoint in use.

Solution: Enable the STS regional endpoint for the delegate region, or configure the connector to use the global STS endpoint.

GCP: service account key

The JSON key file is invalid or expired, or the service account was disabled in the GCP IAM console.

Solution: Verify that the service account is active in GCP IAM. Generate a new key if required and update the Harness file secret.

GCP: project ID mismatch

The service account belongs to a different GCP project than the project being accessed.

Solution: Grant the service account cross-project access through IAM role bindings on the target project.

GCP: missing IAM roles

The service account lacks the IAM roles required for the requested operations, for example, roles/container.admin for GKE.

Solution: Add the required IAM roles to the service account in the GCP IAM console. Common roles include roles/container.developer, roles/storage.admin, and roles/secretmanager.secretAccessor.

Azure: subscription and tenant ID

An incorrect subscription ID or tenant ID produces authentication failures or resource not found errors.

Solution: Verify the subscription ID and tenant ID in the connector configuration against the Azure portal.

Azure: service principal

The service principal secret has expired, or the app registration lacks the required API permissions.

Solution: Check the service principal in Azure AD, then select App Registrations. Verify that the client secret has not expired and that the required Azure role assignments are in place.

Diagnostic steps​

Follow these steps in order to isolate a connector problem systematically, from the Harness UI down to the credential itself.

Step 1: Test the connection from the UI

Start with the built-in connection test. The UI provides a step-by-step breakdown of the connection attempt, covering connectivity, authentication, and authorization, with a detailed error message for each step.

Step 2: Check delegate logs

Examine the delegate logs for detailed error traces. For a delegate running on Kubernetes:

delegate-logs.sh
# Find the delegate pod
kubectl get pods -n harness-delegate-ng

# View delegate logs
kubectl logs -n harness-delegate-ng <delegate-pod-name> --tail=500

# Follow logs in real-time
kubectl logs -n harness-delegate-ng <delegate-pod-name> -f

# Search for specific connector errors
kubectl logs -n harness-delegate-ng <delegate-pod-name> | grep -i "connector\|connection\|auth"
Step 3: Verify network connectivity

From the delegate host, verify that the target endpoint is reachable:

network-diagnostics.sh
# Test HTTPS connectivity
curl -v https://api.github.com

# Test TCP connectivity to a specific port
telnet k8s-api.example.com 6443

# Test DNS resolution
nslookup vault.example.com

# Test with timeout
curl --connect-timeout 5 -s -o /dev/null -w "%{http_code}" https://api.github.com
Step 4: Validate credentials manually

Test the credentials outside Harness to determine whether the problem lies with the credential itself or with the Harness configuration:

credential-validation.sh
# Test GitHub token
curl -H "Authorization: token YOUR_PAT" https://api.github.com/user

# Test AWS credentials
aws sts get-caller-identity

# Test Kubernetes service account token
kubectl --token=YOUR_TOKEN --server=https://k8s-api:6443 get namespaces

# Test Vault token
curl -H "X-Vault-Token: YOUR_TOKEN" https://vault.example.com:8200/v1/sys/health
Step 5: Review the secret manager

Verify that the secrets referenced by the connector are accessible:

  • Confirm that the secret exists at the expected scope: Account, Organization, or Project.
  • Verify that the secret manager itself is healthy, which matters most for external managers such as Vault.
  • Check that the credential was not rotated at the provider without updating the secret value in Harness.
  • For file secrets, such as a GCP service account key or an SSH key, confirm that the content format is correct.

Escalate to Harness Support​

If you complete all diagnostic steps and the issue persists, collect the following information before you escalate to Harness Support:

  • The connector type and identifier.
  • The exact error message.
  • Delegate logs from the time of the failure.
  • Network diagnostic results.
  • The pipeline execution ID, if the failure occurred during a pipeline run.