# Connector and account issues

> Source: https://docs.clonepartner.com/troubleshooting/connectors-and-accounts/

<!-- sources: src/server/api/connectors.ts, src/connectors/catalog-connector.ts, src/connectors/cardamom.ts, references/envoy/connectors.md -->

# 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](/connectors/catalog-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](/security/rbac-secrets-and-hardening/).

:::callout{type="tip"}
When escalating, include the connector type, the failing check name from the test result, and the run ID of a failing task — with credentials and record payloads redacted.
:::

## Related

- [Catalog connectors and connected accounts](/connectors/catalog-and-connected-accounts/) — connect flows and account pinning
- [Hardening, RBAC, and secrets](/security/rbac-secrets-and-hardening/) — how connector secrets are stored
- [Run and executor issues](/troubleshooting/runs-and-executors/) — when the problem is dispatch, not the Connector