Skip to main content

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​

SymptomMost likely causeWhere to look
A placeholder resolved to nothing, and the datapoint received an empty parameterThe namespace does not exist in that scope, or a ref name does not matchNamespaces by scope, Mismatched Reference Names
The datapoint received more than you passed itParameters are merged, not replacedUnexpected Input Parameters
401 Unauthorized or 403 Forbidden from an OLIVE APIThe datapoint has no auth reference, or the caller has no tokenWorks in Development, Fails with 401
401 from an external API, although the auth entry looks rightauth.type is misspelled, so authentication was skipped silentlyauth.type values
The call never leaves OLIVEThe destination is an internal or cluster-internal addressWhere your connectivity may call
A workflow step received null instead of a large resultThe value exceeded what the workflow engine carriesWorkflow Orchestration Limitations
A workflow was terminated mid-runWorkflow history or payload limitsWorkflow Orchestration Limitations
An upload failed with key contains unsupported charactersA space or an unsupported character in the file name or keyKeys and folders
A scheduled task never firesThe platform-side trigger is paused or runs at a slower cadenceScheduling Execution
A datapoint returns its own definition instead of calling anythingNo registered caller claims its datapoint.typeHow to Extend The Modelling Language
A certificate error against an internal test systemThe target presents an untrusted certificateHTTPS Certificate Validation Issues
The editor reported a validation finding but saved anywayValidation is non-blocking by designSemantic Validation Rules

The tools, and what each one is good for​

ToolUse it toNotes
Connectivity TesterRun a connector and see each step's resolved input, result and transformsThe fastest way to find out where in a chain a value went wrong. Inside the platform, no setup
An API client such as BrunoRun an element exactly as a real caller would, including authenticationThe only way to reproduce a caller's problem, because it exercises the token flow too
The debug flagGet execution traces and intermediate steps back in the poll responsePer-request. On by default only in a development deployment — see Debugging Services
Temporal Web UIInspect a workflow run: history, retries, failures, state transitionsOff by default, and only for workflows. Ask your OLIVE operator to enable it on a development deployment
Validation findings in the editorCatch unresolvable refs and bad expressions before you run anythingConnectors only; non-blocking. Datapoints are not semantically validated
Reproduce it in a development deployment first

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​

LevelWritten asWins on a key collision
Caller, through the orchestratorinput: { … }—
Connector elementparameters: { … } on the elementover the previous element's output
Workflow taskwith.parameters: { … }over the previous task's output
Datapoint defaultsdatapoint.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.