# Common errors

> Source: https://docs.clonepartner.com/troubleshooting/common-errors/

<!-- sources: references/envoy/debugging.md, src/task-validator.ts, src/server/api/middleware/error.ts, src/server/config.ts, src/server/secrets/crypto.ts -->

# Common errors

This page covers errors you meet across the product. Look first at the run's logs, then rerun with `--debug` (or per-step `debug: true`) for step input/config/output on stderr, and check the structured server log at `logs/envoy.log`. Connector-specific failures are in [Connector and account issues](/troubleshooting/connectors-and-accounts/); dispatch and executor failures in [Run and executor issues](/troubleshooting/runs-and-executors/).

API errors share one JSON shape from the error middleware:

```json
{ "error": "FORBIDDEN", "message": "Insufficient permissions" }
```

with codes such as `FORBIDDEN` (403), `CONFLICT` (409), `DB_QUERY_TIMEOUT` (503), and `INTERNAL_ERROR` (500).

## Server exits at startup with a config error

**Symptom:** The control plane exits immediately. Stderr shows one of:

- `Server config file not found: <path>`
- `encryption_key is required in server config. Set ENVOY_ENCRYPTION_KEY env var or provide it directly.`
- `Encryption key "default" is not valid base64. Generate one with: openssl rand -base64 32`
- `store.type is "postgres" but no postgres.connection_string is provided` (or the equivalent `mssql` / `victoria_logs` message)

**Cause:** `loadServerConfig` validates the YAML before the server starts; any missing file, unresolvable `${VAR}` reference, invalid encryption key, or backend cross-check failure aborts boot.

**Resolution:**

1. Confirm the `--config` path (or `ENVOY_CONFIG_PATH` in Docker) points at the persisted YAML.
2. Confirm every `${VAR}` referenced in the YAML is set in the process environment — including `ENVOY_ENCRYPTION_KEY` on every restart, not only first boot.
3. Generate a valid key with `openssl rand -base64 32` if the key message appears.
4. Add the backend section the cross-check names. Every rule is listed in [Server configuration](/deployment/server-configuration/).

## API request fails with FORBIDDEN

**Symptom:** A request returns `403` with `{ "error": "FORBIDDEN", "message": "Insufficient permissions" }`.

**Cause:** The `requireRole` middleware rejected the caller's role. Mutating endpoints — connector tests, metrics configuration, imports, run deletion — require `superadmin` or `admin`; viewers get read paths only.

**Resolution:**

1. Check the signed-in user's role under **Users**.
2. Have a superadmin or admin perform the action, or raise the account's role if policy allows.

## Create fails with CONFLICT

**Symptom:** Creating a resource returns `409` with `{ "error": "CONFLICT", "message": "A record with that <field> already exists" }`.

**Cause:** A unique constraint (for example a task or connector name) already holds that value.

**Resolution:** Rename the new resource, or update the existing record instead of creating a duplicate.

## Task validation fails with "Unknown connector type"

**Symptom:** `envoy validate` or the task editor reports `Unknown connector type: '<type>'. Available: <list>`.

**Cause:** The task's `connectors` block names a type that is not registered in this build. Customer builds compile in a selected connector set, and catalog types exist only when the deployment configures a catalog.

**Resolution:**

1. Compare the type against the `Available:` list in the message — check spelling and case.
2. If the type should exist, the deployment needs a build that includes it or a catalog that registers it. See [Customer builds and catalog](/deployment/customer-builds-and-catalog/).

## Task validation fails with "Invalid JSONata expression"

**Symptom:** Validation reports `Invalid JSONata expression: <parser message>` on a step's `config`, `run_if`, `skip_if`, or `batch`.

**Cause:** The expression does not parse — commonly an unbalanced bracket, a stray comma, or YAML indentation cutting the expression short.

**Resolution:**

1. Read the parser message; it includes the failing position.
2. Check the YAML block scalar (`config: |`) captured the whole expression.
3. Validate again before running. See [JSONata reference](/reference/jsonata/).

## Static config contains a JSONata reference

**Symptom:** Validation reports `Static config contains a JSONata reference ('<leaf>'). Static object configs are passed verbatim and never evaluated — convert this step's config to a JSONata string (config: |).`

**Cause:** A step's `config` is a YAML object, and one of its string values references `input`, `steps`, or another JSONata root. Object configs are passed to the step as-is; only string configs are evaluated as JSONata.

**Resolution:** Rewrite the step's `config` as a JSONata string using `config: |`, producing the same object with the references evaluated.

## Warning: $callMethod buffers a streaming method

**Symptom:** Validation warns `$callMethod with method '<method>' returns a collection and is fully buffered into memory, defeating streaming. Use a call_method step as the pipeline source; reserve $callMethod for bounded lookups (find_one, count).`

**Cause:** `$callMethod(...)` inside an expression collects the entire result set in memory before the expression continues, which defeats the streaming pipeline for collection-returning methods.

**Resolution:** Move the collection fetch into a `call_method` step so records stream with backpressure, and keep `$callMethod` for bounded lookups.

## Trigger did not run

**Symptom:** A scheduled Job did not start at its expected time.

**Cause:** The Trigger is disabled, the cron expression or time zone is wrong, the target Job is gone, or a previous triggered run of the same Job is still in flight.

**Resolution:**

1. Confirm the Trigger is enabled and its displayed next-run time is what you expect.
2. Check for another in-flight run of the same Job — see the scheduler entry in [Run and executor issues](/troubleshooting/runs-and-executors/).
3. Confirm scheduler and executor health before re-enabling.

:::callout{type="tip"}
If nothing matches, collect the run ID, the first error and its source, the deployment version, and sanitized logs for the time range before escalating. Redact credentials, tokens, and record payloads.
:::

## Related

- [Connector and account issues](/troubleshooting/connectors-and-accounts/) — test failures and credential errors
- [Run and executor issues](/troubleshooting/runs-and-executors/) — queued, stuck, and interrupted runs
- [Testing and debugging tasks](/building/testing-and-debugging/) — `--debug`, validation, and structured logs