Known issues and limitations

Edit online

Get a quick overview of the known issues and limitations for IBM® watsonx Assistant for Z. As watsonx Assistant for Z is powered by watsonx Orchestrate, this section includes links to known issues of the underlying technology.

Note: For known issues and limitations specific to IBM Software Hub, click here.

ZRAG agent may not retrieve ingested data due to parametric knowledge fallback

The ZRAG agent may not retrieve ingested data when the Parametric Knowledge Fallback flow is triggered because the retrieved documents do not meet the confidence threshold.

Workaround:

To disable parametric knowledge fallback for the affected tenant:
  1. Open the OpenShift console and navigate to the Deployments section.
  2. Select the wxa4z-operator project.
  3. Scale down the operator-controller-manager deployment to 0 replicas.
  4. Switch to the tenant-specific project: wxa4z-<tenant-id>.
  5. Navigate to the ConfigMaps section.
  6. Open the zrag-<tenant-id>-config ConfigMap.
  7. From the actions menu, select Edit ConfigMap.
  8. Locate the ENABLE_PARAMETRIC_FALLBACK variable:
    • If the variable exists, set its value to false.
    • If the variable does not exist, add it with the value false.
  9. Save the ConfigMap changes.
  10. Restart the ZRAG agent pod in the wxa4z-<tenant-id> project to apply the updated configuration.

NATS Pod error in shared namespace impacts Content-Ingestion Pod

The NATS pod in the shared namespace (wxa4z-zad) remains in an error state, and the content-ingestion pod in the tenant namespace reports the following error.
"nats.errors.NoRespondersError: nats: no responders available for request"
Workaround:
Open the ConfigMaps in the shared namespace (wxa4z-zad) and update the wxa4z-nats-config ConfigMap with the following JetStream configuration values.

jetstream {
  store_dir: /data/jetstream
  max_memory_store: 5GB
  max_file_store: 30GB
}
Use the following steps to validate the NATS environment, ensure that the Ingestion Manager creates the worker, and verify that the worker is ready to process jobs:
  1. Scale down the operator.
  2. Scale down the Ingestion Manager.
  3. Delete the NATS PVC.
  4. Restart NATS.
  5. Scale up the Ingestion Manager.
  6. Delete the worker credentials.
  7. Delete the provider-ingestion credentials.
  8. Delete the worker pod and wait for it to restart successfully.
  9. Delete the provider-ingestion pod and allow it to restart.
  10. Verify that the worker is created by the Ingestion Manager and reaches a ready state.
  11. Retry the ingestion operation.

Multilingual Translation and Truncation issues

The zRAG agent intermittently fails to switch response languages in multilingual chat sessions and may occasionally return truncated responses, particularly for French interactions. For example, if the first query is in French and the second query is in English, the agent sometimes continues to respond in French.

Timeout issue with zRAG agents

zRAG agent requests might fail due to the PgBouncer idle transaction timeout setting.

Workaround:
Increase the PgBouncer idle_transaction_timeout value to 300 seconds by applying the following patch: 
oc patch watsonxorchestrates.wo.watsonx.ibm.com/wo \
  -n "${PROJECT_CPD_INST_OPERANDS}" \
  --type=merge \
  -p '{
    "spec": {
      "pgbouncer": {
        "config": {
          "global": {
            "idle_transaction_timeout": "300"
          }
        }
      }
    }
  }'

zRAG agent fails to access watsonx Orchestrate credentials and filters

When you deploy the zRAG agent in watsonx Orchestrate, it fails to access connection credentials or dynamically update filters at runtime.

Workaround:

See zRAG agent fails to access watsonx Orchestrate credentials and filters - Workaround.

Topology service requests fail with 403 when z/OSMF CSRF protection is enabled

Topology service requests to z/OSMF fail with an HTTP 403 response when z/OSMF Cross‑Site Request Forgery (CSRF) protection is enabled, which is the default configuration. The requests do not include the required CSRF headers (X‑CSRF‑ZOSMF‑HEADER or Referer), resulting in authorization failures. As a result, topology service interactions currently succeed only when CSRF protection is disabled

Incomplete responses in multi-turn conversations

Multi‑turn conversations in watsonx Assistant for Z are natural, back‑and‑forth interactions where the assistant collects information step by step, instead of gathering all details in a single form.

During multi-turn conversations with the zRAG agent, users may see the message: “This message was not completed. Please try again.” This typically occurs on the Assistant interface after multiple follow-up queries.

This behavior is due to a current limitation of the Granite 3.3 model when handling extended multi-turn interactions. As the conversation progresses, the model may show inconsistent behavior in invoking tools—especially those that require structured inputs. From the third query onward, this can result in skipped or incomplete tool calls.

Since this limitation is inherent to the model’s instruction-following and context-resolution behavior within the existing controller flow, it cannot be reliably resolved through prompt improvements alone

Workaround:

Start a new conversation session in the Assistant UI and continue your interaction there.

Token limit for conversation context

When the total conversation context exceeds approximately 32,000 tokens, watsonx Assistant for Z returns an HTTP 400 (Bad Request) error with the following message: “Input Tokens Exceed Model Maximum (32768)”.

This limitation is observed in environments that use Spyre or GPU accelerators with the granite‑3.3‑8b‑instruct model.

Workaround:
When the token limit exceeds, the current conversation cannot recover because the accumulated message history continues to exceed the maximum context length. To continue working:
  • Close the current chat and start a new one.
  • Limit each session to one or two job investigations only to prevent the conversation context from exceeding the token limit.

Content ingestion

The following are the recommended limits for ingesting files.
Component Limitation
File size 20 MB per file
File types for remote S3 source PDF, HTML, DOCX, CSV, XLS, XLSX, PPTX, and Markdown.
401 Unauthorized Error in Provider or Content-Ingestion Pods

In some cases, the provider pod in the shared namespace (wxa4z-zad) or the content-ingestion pod in the tenant namespace may encounter a 401 Unauthorized error. This issue typically indicates a problem with authentication credentials used by the pods.

Workaround:

To resolve this issue, do the following:
  1. Delete the wxa4z-ingestion-credentials secret in the secrets section.

    The operator recreates it automatically.

  2. Delete the affected pod, either the provider pod in the shared namespace or the content-ingestion pod in the tenant namespace, depending on where the issue occurs.
  3. Allow the pod to restart.

    The new pod starts without issues.

Although the ingestion process eventually completes successfully, the prolonged duration falls outside acceptable performance limits and indicates a performance limitation within the ingestion workflow.

High ingestion time for large files (≥20 MB)

Content ingestion for large files (≥ 20 MB) is currently experiencing significantly higher processing times than expected. In some cases, ingestion can take more than 5 hours to complete.

Agent fails to start while waiting for wxa4z-client-ingestion

Agents that use the Content Ingestion capability may get stuck during startup after install or upgrade. The agent blocks during startup while waiting for the wxa4z-client-ingestion service to respond; if the ingestion service is not ready or is in an inconsistent state, the agent remains stuck and does not complete startup.

In this state, the agent pod appears in a Running state, but the application server does not start. The agent is not reachable from AI Assistant, and pod logs show ingestion starting but not completing.

Workaround:

See Agent fails to start while waiting for wxa4z-client-ingestion - Workaround.

zChatOps MCP server

When you deploy the zchatops-mcp-server pod, it initially appears in the CreateContainerConfigError state because the required secrets are not yet present. See Deploying zChatOps MCP Server on your cluster.