Known issues and limitations
Get a quick overview of the known issues and limitations for IBM watsonx Orchestrate.
Known issues are identified bugs or unexpected behaviors that can affect your user experience. These issues are typically under investigation or scheduled for resolution in future updates.
Limitations refer to intentional constraints or currently unsupported capabilities due to design, security, or technical reasons. They are not bugs but rather boundaries of what the platform can do.
Being aware of known issues and limitations enables you to plan workarounds and avoid spending time troubleshooting known problems. Stay updated by regularly checking the release notes where the fixes, enhancements, and known issues are documented.
ADK
| Area affected | Description |
|---|---|
| Importing MCP toolkit by using ADK | Keeping the watsonx Orchestrate ADK setup idle for too long can cause an error "Client timeout exceeded while awaiting headers. 500 Internal Server Error" when importing an MCP toolkit. To resolve the issue, run "orchestrate server stop" and then "orchestrate server start". |
| Version conflicts with the requests library | Using different versions of the requests library can lead to compatibility issues. It is essential to ensure that the version you specify aligns with the preinstalled version that is used by the system. Mismatched versions can cause unexpected behavior or failures during execution. For details on the versions used in the Automation Development Kit (ADK), see watsonx Orchestrate ADK GitHub. |
Agents
| Area affected | Description |
|---|---|
| Token refresh failure | If the application's refresh token is expired, you notice an error while you run the tool. To resolve the issue, reconnect the app from the Credentials tab on the Connection settings page. |
| Inconsistent transfer between multi-agent collaborators | In a multi-agent setup, the collaborator agent does not return control to the supervisor agent after the task completion. As a workaround, update the collaborator agent’s configuration to ensure that it transfers control back to the supervisor
agent after task completion. Steps to update Instructions: Note: This workaround does not apply when the collaborator agent is an external agent.
|
| Evaluation threshold in metrics reports | The default threshold is not applied in the evaluation metrics report. As a result, answer quality can be shown as Pass even when the value is lower than the expected threshold. For more information, see Testing your draft agent. |
| Agent evaluation duration | Evaluations sometimes take up to ten minutes to finish. During this time, the evaluation table remains disabled to prevent conflicting changes. When the evaluation is complete, the table is re-enabled and the results are available for review. See Evaluating a draft agent. |
| Purchasing partner agents | The Maven AGI agent is currently unavailable for purchase from the catalog. This agent requires extra detail for agent setup, and the purchase flow doesn’t support collecting that information yet. |
Agent analytics
| Area affected | Description |
|---|---|
| Monitoring messages missing after instance recreation | When you create a new watsonx.governance instance after deleting a previous one, existing agent traces and monitoring messages do not appear on the watsonx.governance dashboard. This issue persists even after
you reactivate monitoring. |
| Dashboard requires login after opening in new tab | On the agent analytics page, clicking "View dashboard" opens a new browser tab and prompts for login, rather than displaying the dashboard directly. |
AI assistants
| Area affected | Description |
|---|---|
| Digression | Users can't digress to the default action behavior when they interact with actions from skills on AI assistants. |
| Language support for AI assistant builder | The AI assistant builder supports the English language only. |
| Authentication on AI assistant API with IP address restriction | To use AI assistant builder API with an IP address restriction, use a bearer token in an authorization header instead of an API key. |
| Interactions containing media and UI widgets are not supported | Interactions with AI assistants are limited only to text. Response types such as media and UI widgets are not supported. |
| AI assistants sourced from the same instance as a collaborator agent | AI assistants from the AI assistant builder must be sourced from instances other than the instance that you use to build the agent. It is not supported adding AI assistants sourced from the same instance as a collaborator agent. |
| AI assistants hosted on IBM watsonx Orchestrate on AWS | Adding AI assistants from the AI assistant builder as a collaborator agent is available only for IBM watsonx Orchestrate on IBM Cloud. It is not supported for IBM watsonx Orchestrate on AWS. |
| AI assistant access failure for admin users added through SSM | In AWS environments, for admin users added through SSM, when you access the AI assistant builder, the page fails to load and prevents from managing AI assistants. To resolve the issue temporarily, remove and re-add the affected admin user through the Manage Users page. This restores access to the AI assistant builder. A permanent fix is expected once MCSP is updated to support multiple admin users. |
Channels
| Area affected | Description |
|---|---|
| Preview in channels | Billing functionality is not fully implemented. The system cannot send complete user context, including user_id and related metadata. Also, the ongoing bugs affect channel compatibility with flows. As new runtime capabilities
are introduced, corresponding channel features will be progressively ported and made available in future releases. |
Orchestrate Chat
| Area affected | Description |
|---|---|
| Orchestrate Chat scrolling in Safari | You might not be able to scroll the Orchestrate Chat window in Safari versions earlier than iOS 18.2 because of a browser bug that blocks momentum scrolling. Update Safari to version 18.2 or later to fix the issue. |
| watsonx Orchestrate preview chat | The option to enter team credentials for an app or tool isn’t available in the preview chat for builders. As a result, you might see an error: "Authentication failed using the team credentials. Contact your administrator to update the credentials." |
| Uploading files on watsonx Orchestrate chat | When you upload files through the watsonx Orchestrate chat, trying to reupload an existing file causes an error: "File is already uploaded". To resolve the issue, ensure you're uploading unique files each time. |
| Document upload fails | The document that is uploaded in the AI agent chat might fail for files more than 8 MB due to a timeout limit. To avoid this issue, ensure that the uploaded documents are 8 MB or smaller. |
| Embedded chat disappears | When you minimize and reopen an embedded full-screen chat with a sidebar, it starts a new session. When you attempt to access the previous chat, it causes the embedded view to disappear. |
| Chat with documents is not supported in voice (Preview) | The AI agent's document chat functionality is not supported for voice input. |
| Chat ignores mandatory inputs | Tools can have multiple required inputs. An issue exists for agents using lower accuracy models where all mandatory inputs are not recognized by the chat. The chat recognizes only the first input, and it might ignore the other mandatory inputs. To work around this issue, change the agent style to "ReAct" in the "Profile" section of the agent. |
| Chat-based table search results are not editable | You cannot edit or delete rows that are returned when you filter or search a table in a chat. |
Connections
| Area affected | Description |
|---|---|
| Changing auth type for live connections | You might face issues when you try to change the auth type for live connections. If the draft and live environments use different auth types, you cannot deploy your tool or agent. As a workaround, you can create a new connection with the correct auth type, rebind it to your tool, and then deploy. |
| Editing connection details | When you switch the authentication type in a saved connection and deleting the associated runtime credentials, the system might return a "credential not found" message. It occurs only if the user performs both actions - switching the auth type and reconnecting in a single flow, which is not supported. |
Tools
| Area affected | Description |
|---|---|
| Async tool support | Currently, watsonx Orchestrate does not support asynchronous Python tools end-to-end. When a custom tool is designed to run asynchronously, such as using threading or asyncio to handle concurrent tasks, the system does not properly await its response. |
| Tool execution fails to invoke the tool | Tool execution fails on the first attempt to invoke the tool and succeeds during the second attempt on the same thread. If you encounter a failure after a prolonged period of inactivity, retry the execution once. |
| Duplicate properties in the input schema | If the input schema objects for a tool contain duplicate properties, the system performs a validation check to prevent the tool addition. This validation check is required to avoid conflicts when asking for inputs and is an expected behavior. |
| Unable to scroll the extracted fields | If you add up to 25 fields in the document extractor, the scroll bar is not displayed, preventing you from viewing all the extracted fields. |
| Preview of the send for human review in flows | Previewing the send for human review in document processing is not supported. |
| Optional model support | The optional meta-llama/llama-3-2-11b-vision-instruct model for document extractor and document classifier is not supported in certain regions (Asia Pacific (AP) South and Tokyo). For more information, see Regional availability of provided foundation models. |
| Chat displays an error and users are not prompted for inputs | If you are using the GPT‑OSS 120B‑OpenAI model (via Groq) with the ReAct agent style, an error is displayed in the chat and users are not prompted for inputs. To resolve this issue, follow the best practice of adding agent instructions. To do so, in the Agent Builder (Manage agents page), add instructions in the Behavior section that direct the agent to prompt users when required inputs are missing. You can add the following Behavior instruction - If required inputs are missing, do not speculate. Ask for the minimum missing fields in a single question and wait.For more information about adding Behavior instructions, see, Using the GPT‑OSS 120B model with Groq - Special considerations  and add one or more instruction blocks to your agent. |
Tools - Agentic workflows
| Area affected | Description |
|---|---|
| Default inputs used in a nested agentic workflow | The expected behavior is that the engine will prompt the user to provide inputs to the tool if they cannot be computed. However, instead of a prompt, a default value is used. If there are no inputs in the parent workflow that can automatically map to the inputs of the tools, or if there are no user activity nodes collecting relevant inputs to the tool, the workflow calls the tool using automapping and generates default inputs for the tool. To pass specific values or null values for these inputs, they must be explicitly modified in the data mapping. |
| Agent fails to deploy | An agent fails to deploy if it includes a workflow that was created previously in the technology preview. To resolve this issue, open the workflow in the agentic workflow builder and edit the name, or description and save it. Saving the workflow updates the workflow configuration to work with the general availability release. |
| Automapping in forms | In an agentic workflow, automapping does not work for form fields such as boolean, date range, and other fields. |
| Agentic workflow input date format | For date input fields, you must provide date inputs in ISO format only (yyyy-mm-dd). If the input is not in ISO format, the workflow returns an error. |
| Observability | The system does not currently include the agentic workflow runtime events in observability traces when the workflow is not associated with an agent. For example, this occurs when you initiate an agentic workflow through the Flow APIs. For more information about observability, see Monitoring agents. |
Generic issues
| Area affected | Description |
|---|---|
| Application tiles load slowly on the home screen | The loading and display time of application tiles on the watsonx Orchestrate home page might be prolonged, particularly when there are many applications present on your home screen. The issue is prioritized and considered as part of future enhancements. |
| Memory persistence in watsonx Orchestrate | When you refresh the browser, or log out of your active watsonx Orchestrate instance, watsonx Orchestrate is reset. For example, if you use the "Find candidates for a job" skill to generate a list of candidates then click the header to go back to the home page, your results from the previous query is gone. To avoid this limitation, consider completing the course of action before you leave the context of your actions (downloading and emailing applicants after you retrieve the candidate list). |
| Authentication on watsonx Orchestrate API with IP address restriction | To use the watsonx Orchestrate API with an IP address restriction for watsonx Orchestrate on IBM Cloud, use a bearer token in an authorization header instead of an API key. For more information about IP address restriction on IBM Cloud, see Allowing specific IP addresses for an account. |
IBM SaaS Console
| Area affected | Description |
|---|---|
| Billed usage | The IBM SaaS Console is not showing billed usage information. |
| Subscription access in SaaS Console | Newly added admins in the SaaS Subscription Management (SSM) UI do not have access to subscriptions that were initially created by the first admin in the SaaS Console. |
Language support
| Area affected | Description |
|---|---|
| Japanese language support | The following features are not supported in Japanese: - AI Assistant Builder (English only). - The Feedback section in the Orchestrate Chat interface. - Connection parameter names and Credential management on the Connections page. |
Login issues
| Area affected | Description |
|---|---|
| Issues with watsonx Orchestrate login experience on Chrome v128 | When you log in to watsonx Orchestrate by using Chrome version 128.0.6613.85, the landing page is either slow or doesn't render. A blank page appears upon selecting a tenant. Browser refresh might not help, but holding the shift key while you refresh the browser takes you to the tenant. To resolve the issue, upgrade Chrome to version 128.0.6613.120 (Official Build). |
| Log in to watsonx Orchestrate | Sometimes, when you log in to watsonx Orchestrate, it displays an error that says "We couldn't find you", which results from cache issues. To troubleshoot this problem, clear your cache. |
Models
| Area affected | Description |
|---|---|
| Llama limitation | When you try to initiate multiple collaborator agent tools in a single utterance, the expected tool calls might not run due to a limitation in the Llama model. |
Repetitive responses by model Llama-3-3-70b-instruct |
The model might exhibit repetitive patterns, especially when you engage in long conversations or certain scenarios, generating the same response regardless of changes in the input. Use Llama-3-2-90b-vision-instruct as an alternative.
Also, if you need to integrate external models, use the AI Development Kit (ADK) to bring in custom or third-party models into your environment. |
Llama-3-2-70B-instruct model context length |
The model's capacity to retain past conversation history might decrease based on available memory, impacting the maximum supported context length. |
| LLM hallucination and incorrect agent routing | When an LLM encounters an utterance that falls outside its tool capabilities, it can hallucinate and incorrectly route the request to an unrelated collaborator agent. Models like llama and Granite are suitable for experimentation but tend to hallucinate more in complex scenarios. For production use, prefer paid models for better reliability and reduced hallucination. |
Repeated tool calls with Llama-3-405b-instruct |
When you use the Llama-3-405b-instruct model, reAct-style agents call the same tool multiple times even after receiving a successful response. This behavior is less frequent with models like llama-3-2-90b-vision-instruct and
others. |
| Running tool with Gemini model | Running tools in the chat on watsonx Orchestrate is not supported on the gemini-2.0-flash and gemini-2.5-pro models. |
| Gemini tool invocation | Gemini models occasionally fail when you start a tool, returning an UNEXPECTED_TOOL_CALL error. A temporary workaround is to retry the request. |
| Gemini-2.0-flash usage | The gemini-2.0-flash model does not support React-style usage. |
Tenants
| Area affected | Description |
|---|---|
| Missing API key and URL on new tenants | When you create a new watsonx Orchestrate tenant on IBM Cloud, the API Key and URL are missing from the Launch Instance page where you see the "Launch watsonx Orchestrate" button. |
| Interacting with different tenants in the same browser window is not supported | When users attempt to access multiple tenants of watsonx Orchestrate from the same browser window, session cookies cause tenant data to be shared across active sessions. As a workaround, use separate browser profiles, different browsers, or Firefox containers to isolate tenant sessions and prevent shared cookies from causing conflicts. |
Voice
| Area affected | Description |
|---|---|
| Chat with documents is not supported in voice (Preview) | The AI agent's document chat functionality is not supported when you use voice input. |
watsonx Orchestrate API
You might encounter known issues and limitations when you use the methods of the watsonx Orchestrate API.
To get a quick overview of the known issues and limitations for the API, see the IBM watsonx Orchestrate API documentation page.