My workflow is not doing what I expect
The first diagnostic step is usually to temporarily display the suspected value in a Simple message with {{codeblock myVariable}}.
The bot does not answer
Probable cause: Start is not connected, or a route ends without a block that produces an answer.
Where to look: follow every link from Start, including Else and failure branches. Check the problems panel.
Fix: connect every route to a response, an action that cleanly ends the turn, or a fallback.
A variable is empty or displayed literally
Probable cause: the identifier or alias changed, the reference contains a typo, or the producer block did not run on this route.
Where to look: type {{ in the field and compare suggestions with your reference. Display the producer block’s complete output.
Fix: select the variable from autocomplete, close its braces correctly ({{block.output}}), and confirm that the producer ran before the value is used. A variable appearing in the suggestions does not guarantee that its block runs on the tested route.
I cannot select my embedding model or sources
Probable cause: the model’s index is not provisioned, or the sources are incompatible with the selected model.
Where to look: the Embedding model and Data sources fields of the Data Sources block. A model marked no index provisioned cannot be selected.
Fix: select an available model, then its compatible sources. After changing the model, review the selection again: incompatible sources are removed. If the expected model or sources remain unavailable, contact your administrator.
My source or tool provider is missing
Probable cause: the block is connected to the main path, already assigned to another connection, or does not supply the expected data.
Fix: leave the provider without incoming or outgoing main-path links, then select it from Contextual ports on the block that uses it. See the connection guide for the steps.
The bot does not cite documents
Probable cause: MCP Retriever is unavailable, the model does not call it, or the instruction does not require citations from its results.
Where to look: inspect {{listTools-1.tools}}, {{chatCompletion-1.genericToolCalls}}, then {{codeblock callTools-1.toolCallResults}}. Also check the Retriever server URL, allowed tools, and metadata.
Fix: make retriever_retrieve_information available, pass the catalog to both the LLM instruction and request, then require a search before answering and citations containing available document names and pages.
If you use a block with Contextual ports, also check the selected source and tool providers, along with that block’s instructions and fields.
The user sees a technical error
Probable cause: an After failure output is not connected.
Where to look: LLM requests, MCP catalogs, tool calls, and any business HTTP calls unrelated to RAG.
Fix: connect each failure to a message such as: “I encountered a technical issue. Please try again in a few minutes.”
An MCP tool is never called
Probable cause: tools are not passed to the LLM request, or the genericToolCalls condition is incorrect.
Where to look: the request must receive {{listTools-1.tools}}. The condition can use gt (length chatCompletion-1.genericToolCalls) 0 without braces around the whole expression.
Fix: inspect the complete chain: catalog → instruction → LLM request → condition → tool call → return to the same LLM instruction. The next request must read the instruction rebuilt with the tool results. For a block offering a tool connection, check the provider selected in Contextual ports and the tools allowed in its catalog.
Studio asks for confirmation when saving
Probable cause: missing required field, unknown reference, or invalid JSON.
Where to look: the problems panel lets you navigate to every affected field.
Fix: resolve issues one at a time. Headers are objects {}, HTTP codes are arrays [200], and documents are arrays of objects. Studio allows saving with issues after confirmation; fix them before using the workflow with users.
A condition always chooses the same route
Probable cause: unexpected value type, entire expression wrapped in braces, empty variable, or overly complex condition.
Fix: display each value, reduce the expression to one simple test, then recombine tests with and, or, or not.
An HTTP call works outside Studio but fails here
Check Content-Type, body type, interpolated headers, accepted codes, response format, network access from the platform, and timeout.