6.16 Troubleshooting Connectivity
Connectivity fails in a small number of recognisable ways, and the tool that shows you why differs for each. This page is the entry point: find the symptom, and it tells you where to look.
Start here
| Symptom | Most likely cause | Where to look |
|---|---|---|
| A placeholder resolved to nothing, and the datapoint received an empty parameter | The namespace does not exist in that scope, or a ref name does not match | Namespaces by scope, Mismatched Reference Names |
| The datapoint received more than you passed it | Parameters are merged, not replaced | Unexpected Input Parameters |
401 Unauthorized or 403 Forbidden from an OLIVE API | The datapoint has no auth reference, or the caller has no token | Works in Development, Fails with 401 |
401 from an external API, although the auth entry looks right | auth.type is misspelled, so authentication was skipped silently | auth.type values |
| The call never leaves OLIVE | The destination is an internal or cluster-internal address | Where your connectivity may call |
A workflow step received null instead of a large result | The value exceeded what the workflow engine carries | Workflow Orchestration Limitations |
| A workflow was terminated mid-run | Workflow history or payload limits | Workflow Orchestration Limitations |
An upload failed with key contains unsupported characters | A space or an unsupported character in the file name or key | Keys and folders |
| A scheduled task never fires | The platform-side trigger is paused or runs at a slower cadence | Scheduling Execution |
| A datapoint returns its own definition instead of calling anything | No registered caller claims its datapoint.type | How to Extend The Modelling Language |
| A certificate error against an internal test system | The target presents an untrusted certificate | HTTPS Certificate Validation Issues |
| The editor reported a validation finding but saved anyway | Validation is non-blocking by design | Semantic Validation Rules |
The tools, and what each one is good for
| Tool | Use it to | Notes |
|---|---|---|
| Connectivity Tester | Run a connector and see each step's resolved input, result and transforms | The fastest way to find out where in a chain a value went wrong. Inside the platform, no setup |
| An API client such as Bruno | Run an element exactly as a real caller would, including authentication | The only way to reproduce a caller's problem, because it exercises the token flow too |
The debug flag | Get execution traces and intermediate steps back in the poll response | Per-request. On by default only in a development deployment — see Debugging Services |
| Temporal Web UI | Inspect a workflow run: history, retries, failures, state transitions | Off by default, and only for workflows. Ask your OLIVE operator to enable it on a development deployment |
| Validation findings in the editor | Catch unresolvable refs and bad expressions before you run anything | Connectors only; non-blocking. Datapoints are not semantically validated |
Almost everything is easier to diagnose where there is no authentication, every element is editable, the debug flag is on, and the Temporal UI can be enabled. If a problem appears only in a production deployment, the difference is usually authentication or roles rather than the connectivity itself — the two usual suspects are listed in From a Development Deployment to Production.
Where "input" actually goes
The single most common source of confusion is that the word input means something different in five places. The same connector, invoked the same way, needs a different payload shape depending on what you are using to invoke it.
Invoking through the Data Orchestrator
Parameters go inside an input object, next to the id of the element:
{
"id": "helloworld-c1-hello-world-to-summary",
"input": {
"url": "https://en.wikipedia.org/wiki/Artificial_Intelligence_Act"
}
}
This is the shape for data-orchestrator/v1/invoke, and therefore the shape an API client, a script, an
Excel workbook or an agent application sends.
Invoking from the Connectivity Tester
The tester asks only for the element's parameters, so they go at the top level with no input
wrapper:
{
"url": "https://en.wikipedia.org/wiki/Artificial_Intelligence_Act"
}
The tester adds the envelope for you. Pasting an API-client body into the tester produces an element that
receives a single parameter called input, which is almost never what the element expects — and the
other way round, pasting a tester body into an API client sends no parameters at all.
Inside a connector element
An element declares what it passes to the element it calls under parameters:
{
"element": "helloworld-dp2-hello-world-summary-prompt",
"parameters": {
"content": "${ref.httpResponse}"
}
}
Inside a workflow task
A call task declares them under with.parameters, beside the id of the element to run (with.datapoint, which takes any connectable element):
{
"summarize": {
"call": "olive",
"with": {
"datapoint": "helloworld-dp2-hello-world-summary-prompt",
"parameters": {
"content": "${httpContent}"
}
}
}
}
On the datapoint itself
A datapoint may declare default parameters, which are merged with whatever arrives:
{
"datapoint": {
"type": "http",
"parameters": {
"model": "gpt-5"
}
}
}
How they combine
| Level | Written as | Wins on a key collision |
|---|---|---|
| Caller, through the orchestrator | input: { … } | — |
| Connector element | parameters: { … } on the element | over the previous element's output |
| Workflow task | with.parameters: { … } | over the previous task's output |
| Datapoint defaults | datapoint.parameters: { … } | loses to the incoming values |
Two merges happen on the way in, and neither can be switched off: the previous element's output is merged
with the current element's parameters, and that result is merged with the datapoint's own
parameters. This is why a datapoint often receives more than you passed it — see
Unexpected Input Parameters for the three ways to
control it.
Inside the element, all of it arrives as ${input.…}, whichever level it came from.
When you report a problem
Include the request ID from the response or the log. Every log record carries it, so it is the fastest
way for an operator to reconstruct what happened across every service the request touched. Quote it
alongside the element id and the jobID.
Related
- Common Pitfalls — the specific failures above, with worked examples
- Semantic Validation Rules — what the editor checks before you run anything
- Debugging Services — the debug flag and cluster-level observability
- Troubleshooting & Debugging — workflows specifically