Skip to main content

15 Common Pitfalls

This chapter collects the failures connectivity engineers hit most often, with worked examples. If you are starting from a symptom rather than a known cause, begin at Troubleshooting Connectivity, which maps symptoms to the tool and the page that explains them.

Unexpected Input Parameters​

By default, all input a datapoint receives is attached to its parameters. In the case of HTTP parameters in connectors, this means that the request body is created by merging the parameters defined in the connector with the input it receives.

Example​

{
"id": "test-c1-connector-public",
"type": "connector",
"version": "0.0.1",
"tags": [
"training"
],
"connector": {
"elements": [
{
"ref": "dpOne",
"element": "test-datapoint-get",
"parameters": {
"objectID": 7
}
},
{
"ref": "adonisGetRepos",
"element": "adonis-rest-get-repos"
},
{
"ref": "destination",
"element": "test-datapoint-post-echo",
"parameters": {
"firstItem": "${ref.dpOne}",
"secondItem": "${ref.adonisGetRepos.repos[0].id}"
}
}
]
}
}

In this example, the test-datapoint-post-echo datapoint receives an object with a firstItem key and a secondItem key. In addition, it also receives the output of the previous element in the connector. In this case, that is the output of the adonis-rest-get-repos datapoint, which is passed as part of its parameters.

Why this happens​

Two merges take place on the way into a datapoint, and neither can be switched off:

  1. In the connector, the previous element's output is merged with the parameters declared on the current element. parameters win on a key collision.
  2. In the datapoint, that result is merged with the parameters declared on the datapoint itself. The incoming values win on a key collision.

The merge is deep, so nested objects are combined rather than replaced.

How to avoid it​

There is no flag that restricts a datapoint to its declared parameters. Shape the payload instead:

  • Put a transform datapoint in front of the call. A transform element that emits only the keys the endpoint expects is the reliable way to drop everything else: "transform": "${ { 'firstItem': input.firstItem, 'secondItem': input.secondItem } }".
  • Use an input transformer on the datapoint. input.transformer.transform runs before the request is built and sees the merged payload, so it can select the fields that should survive. See Transforming Connectivity Input & Output Data.
  • Set an explicit body on the HTTP datapoint. A declared datapoint.http.body is used as-is and is not merged with the incoming parameters, so it is the narrowest option when the request shape is fixed.
strict is not a supported option

Earlier versions of this handbook, and some older example definitions, referred to a strict flag as the way to suppress this merge. There is no such property in the connectivity metamodel, and setting it has no effect — it is ignored. Use one of the three approaches above.


Mismatched Reference Names​

Example​

❌ Incorrect usage — ref.adonisGetRepos does not exist in this connector; the first element's ref is firstCall:

{
"id": "training-c1-connector",
"type": "connector",
"version": "0.0.1",
"tags": ["examples", "training"],
"connector": {
"elements": [
{
"ref": "firstCall",
"element": "adonis-rest-get-repos"
},
{
"ref": "secondCall",
"element": "adonis-rest-get-stats",
"parameters": {
"content": "${ref.adonisGetRepos.repos[0].id}"
}
}
]
}
}

✅ Correct usage — the placeholder matches the earlier element's ref:

{
"id": "training-c1-connector",
"type": "connector",
"version": "0.0.1",
"tags": ["examples", "training"],
"connector": {
"elements": [
{
"ref": "firstCall",
"element": "adonis-rest-get-repos"
},
{
"ref": "secondCall",
"element": "adonis-rest-get-stats",
"parameters": {
"content": "${ref.firstCall.repos[0].id}"
}
}
]
}
}

Symptom​

  • Error like Cannot resolve reference path: ref.<name>.

Cause​

  • The placeholder ${ref.<name>...} uses a name that does not match any previous element’s ref.

Fix​

  • Ensure an exact match with the prior element’s ref.
  • Example fix: ${ref.firstCall.repos[0].id} instead of ${ref.adonisGetRepos...}.

Tip​

  • After renaming a ref, search and replace all ${ref.*} usages.

Output/Input Schema Mismatch​

Example​

❌ Incorrect usage — ref.firstCall.repos is the whole array, where the target expects a single id string:

{
"id": "training-c1-connector",
"type": "connector",
"version": "0.0.1",
"tags": ["examples", "training"],
"connector": {
"elements": [
{
"ref": "firstCall",
"element": "adonis-rest-get-repos"
},
{
"ref": "secondCall",
"element": "adonis-rest-get-stats",
"parameters": {
"content": "${ref.firstCall.repos}"
}
}
]
}
}

✅ Correct usage — one element of the array, matching the shape the target expects:

{
"id": "training-c1-connector",
"type": "connector",
"version": "0.0.1",
"tags": ["examples", "training"],
"connector": {
"elements": [
{
"ref": "firstCall",
"element": "adonis-rest-get-repos"
},
{
"ref": "secondCall",
"element": "adonis-rest-get-stats",
"parameters": {
"content": "${ref.firstCall.repos[0].id}"
}
}
]
}
}

Symptom​

  • Runtime errors such as undefined, 400 Bad Request, or 500 Internal Server Error when the downstream datapoint receives a value in an unexpected shape or type.
  • Example: passing an entire object or array instead of a string field required by the endpoint.

Cause​

  • The output structure of the previous datapoint, defined under {output.schema}, does not match the input structure expected by the next datapoint, defined under {input.schema}.
  • Currently, there is no schema validation between datapoints, so these mismatches go undetected until runtime.

Fix​

  • Verify the output schema of the source datapoint ({output.schema}) and the input schema of the target datapoint ({input.schema}).
  • Adjust parameter references to point to the correct field and data type.
  • Example fix: use ${ref.firstCall.repos[0].id} instead of ${ref.firstCall.repos}.

Tip​

  • When unsure, check the datapoint’s {output.schema} definition to confirm the output shape.
  • Log or preview the output to inspect the actual runtime data before wiring it into another element.
  • Even though schema validation is not yet enforced, it is strongly recommended to already define both input.schema and output.schema for every datapoint.
    • This ensures forward compatibility once validation and autocomplete features are introduced.
    • It also serves as clear documentation of the expected input and output for each datapoint.

Works in Development, Fails with 401 in an Authenticated Environment​

Symptom​

A datapoint or connector that has worked for weeks in a development deployment starts failing after being moved to an authenticated environment — a 401 Unauthorized, or a 403 Forbidden when a client is authenticated but lacks the role. Nothing in the definition was changed.

Cause​

A development deployment has no authentication, so OLIVE's public APIs accept requests there without credentials. The datapoint calls an OLIVE API — file-storage-service, session-memory, data-orchestrator, repository — and has no auth reference:

❌ Works in development only:

{
"id": "mysolution-dp-read-file",
"type": "datapoint",
"version": "0.0.1",
"datapoint": {
"type": "http",
"http": {
"url": "https://api.<tenant>.<cluster>.<domain>/file-storage-service/get?key=${input.key}",
"method": "GET"
}
}
}

Fix​

Reference an Auth entry of type oidc, using one of the clients provisioned during tenant onboarding:

✅ Works in both:

{
"id": "mysolution-dp-read-file",
"type": "datapoint",
"version": "0.0.1",
"datapoint": {
"type": "http",
"http": {
"url": "${input.apiBaseUrl}file-storage-service/get?key=${input.key}",
"method": "GET"
},
"auth": "mysolution-a-oidc-olive-platform"
}
}

How to set up the auth entry is described in Calling OLIVE's own APIs from connectivity.

The same applies to whatever triggers the connectivity​

A 401 on the invoke call itself has the same cause one level further out: the caller invoked data-orchestrator/v1/invoke anonymously in development and now has to obtain a token. See Triggers that worked without credentials in development.

Tip​

Both changes belong to taking a solution from development into productive use. Why they are needed, and how to plan them in while you are still developing, is described in The two changes you will almost always have to make.


HTTPS Certificate Validation Issues in data-orchestrator​

By default, the data-orchestrator does not resolve HTTPS datapoints that present an invalid or untrusted TLS certificate.

In such environments, TLS certificate validation can be disabled for the data-orchestrator, or any other Express-based service, by configuring an environment variable in the deployment’s values.yaml file.

See also: https://nodejs.org/api/cli.html#node_tls_reject_unauthorizedvalue

Workaround for Development Environments​

  1. Open the values.yaml file of the OLIVE Platform deployment.

  2. Add the following configuration snippet:

    values.yaml

data-orchestrator:
express:
env:
NODE_TLS_REJECT_UNAUTHORIZED: "0"
  1. Redeploy the data-orchestrator service to apply the change.

Make sure to redeploy the data-orchestrator deployment so that the change is applied.

Important Security Notice​

Setting NODE_TLS_REJECT_UNAUTHORIZED=0 disables TLS certificate verification for all HTTPS requests executed by the Node.js process.

This substantially weakens transport security and must only be used in controlled, non-production environments. Use with extreme caution.