Connector and account issues

Start every connector problem with the built-in connection test: Test on the Connector, backed by POST /api/connectors/:id/test (or POST /api/connectors/test for an unsaved config). Both endpoints require the superadmin or admin role, call the connector's testConnection(), and abort after 30 seconds with Test connection timed out after 30s.

Connection test fails or times out

Symptom: The test returns an error, or Test connection timed out after 30s.

Cause: Four distinct failure classes produce this: name resolution or routing (the host is unreachable from the testing process), TLS (certificate name, trust chain, or interception), authentication (invalid, expired, or mis-scoped credentials), or authorization/schema (login works but the resource or method is denied). A timeout usually means routing or a firewall silently dropping packets.

Resolution:

1. Read the failing check in the test result — most connectors return per-check detail rather than one flat error.
2. Classify the failure: DNS/route, TLS, credential, or permission.
3. Remember the test runs on the control plane, while task execution may run on a remote executor with different network access. Reproduce with one bounded Task if the test passes but runs fail.

Test passes on the control plane but tasks fail on the executor

Symptom: Test succeeds, but the same Connector fails inside a run with a connection or file-not-found error.

Cause: Control plane and executor are different containers. The executor may lack network egress to the data source, or the file path is not mounted there.

Resolution:

1. For network connectors, verify executor egress rules to the source and destination.
2. For file connectors, use absolute container paths under mounts shared by both services (/app/data, /app/dbs); relative paths fail on the executor's read-only root filesystem.

Catalog connected account stops working

Symptom: A catalog Connector that worked starts failing method calls, or its connection test fails on the credential checks.

Cause: Catalog connectors resolve credentials for the connected account (optionally pinned as integrated_account_id on the Connector) from the credential vault at call time. If the provider authorization behind the account expired or was revoked, credential resolution fails even though the Connector record is unchanged.

Resolution:

1. Run the connection test. It checks, in order: catalog initialization, integration definitions (file catalogs must contain *.json integration files — otherwise No *.json integration files found in <dir>), catalog service reachability, credential-vault reachability, and the pinned account's credentials.
2. If the pinned-account check fails, reconnect the account through Connect account on the Connector and re-authorize with the provider.
3. If the catalog checks fail, verify the deployment's catalog settings (clove_url/clove_token or integrations_dir) — a missing token fails with clove_token is required when clove_url is set. See Catalog connectors and connected accounts.

File upload rejected

Symptom: Uploading through the Data Explorer Upload action or POST /api/connectors/:id/files fails.

Cause: Uploads are limited to connectors that declare the upload capability, capped by connectors.upload_max_bytes (default 25 MiB), restricted to superadmin/admin, and path-checked: local file connectors reject absolute paths, .. traversal, and symlinks resolving outside the configured base directory. CSV connectors accept only .csv; YAML connectors only .yaml/.yml.

Resolution:

1. Check the file size against the configured limit; raise connectors.upload_max_bytes in server config if policy allows.
2. Use a relative path under the connector's directory (or the object key for S3, blob name for Azure).
3. Confirm the connector's base directory is mounted in the server container — and in the executor when tasks read the file later.

Connector saved but secrets cannot be read

Symptom: Opening or testing an existing Connector fails with a secret or decryption error while new Connectors work.

Cause: Stored connector configs are secrets, encrypted with the deployment's encryption_key or held in the configured vault. A changed key or an unreachable vault makes existing records unreadable.

Resolution:

1. Confirm the deployment is running with the same ENVOY_ENCRYPTION_KEY as when the Connector was created.
2. For vault-backed secrets, verify vault reachability and permissions.
3. If the key was lost, the encrypted material is unrecoverable — re-enter the connector credentials. See Hardening, RBAC, and secrets.

Related

• Catalog connectors and connected accounts — connect flows and account pinning
• Hardening, RBAC, and secrets — how connector secrets are stored
• Run and executor issues — when the problem is dispatch, not the Connector