Troubleshooting

Installing the watsonx Orchestrate Developer Edition

You might encounter errors when installing the watsonx Orchestrate Developer Edition. To address the most common errors, see the following topics for solutions:

server start command fails with pull access denied

Try to log in manually with the following command:
```
docker login -u cp -p APIKEY cp.icr.io
```
If you manage to log in and the server still fails to start, locate the Docker config file. Usually, you find this file in ~/.docker/config.json. If it doesn’t exist, you can create it.
Add the following content to the file:
```
{
  "auths": {
    "us.icr.io": {
      "auth": "BASE64_ENCODED_APIKEY"
    }
  }
}
```
Where BASE64_ENCODED_APIKEY is the base64 encoded string of iamapikey:DOCKER_IAM_KEY.

Permission denied when trying to download Docker images

You get an error message such as the following one:

dial unix /var/run/docker.sock: connect: permission denied

This issue happens because the Docker daemon runs as a root-owned process that communicates through a Unix socket. You must have the necessary permissions to access this socket.

To solve this problem, follow these steps:

Add Docker to the group of users that can use sudo.
```
sudo usermod -aG docker $USER
```
Run the following command to log in to a new group:
```
newgrp docker
```
Check if your user belongs to the docker group:
```
groups
```
Try running Docker’s hello-world to check if you’re able to run Docker:
```
docker run hello-world
```

For Windows users, you might also encounter containerization issues as Windows systems do not support Docker natively.

No environment file

If you’re using Windows, you may have created your .env file on your local machine. To make it accessible within your Ubuntu environment in WSL, follow these steps:

Open File Explorer and enter the following path in the address bar, replacing yourUsername with your actual Linux username:

[PATH]

\\wsl.localhost\Ubuntu\home\yourUsername

Open another File Explorer window and navigate to the location where your .env file is saved.
Copy the .env file into your Linux home directory shown in the first window.

The Compose file is invalid because of unsupported variable types

If you get an error similar to this:

ERROR: The Compose file '/home/user/adktest/.venv/lib/python3.12/site-packages/ibm_watsonx_orchestrate/docker/compose-lite.yml' is invalid because:
services.wxo-server-worker.environment.DO_NOT_TRACK contains true, which is an invalid type, it should be a string, number, or a null
services.wxo-tempus-runtime.environment.REDIS_TLS contains false, which is an invalid type, it should be a string, number, or a null
services.wxo-server.environment.DO_NOT_TRACK contains true, which is an invalid type, it should be a string, number, or a null
services.socket-handler.build contains unsupported option: 'ssh'
services.wxo-server-worker.depends_on contains unsupported option: 'required'
services.wxo-server.depends_on contains unsupported option: 'required'

That’s because you’re using an older version of Docker Compose (v1 instead of v2) that does not support some variable types.

To solve this issue, you must install Docker Compose v2.

On Ubuntu 24.04, for example, you can simply run the following commands:

sudo apt-get remove docker-compose
sudo apt-get install docker-compose-v2

Check your distribution repositories for the appropriate packages of Docker Compose v2.

Homebrew not installed in Ubuntu

If Homebrew is not installed in your Ubuntu distribution on WSL, you’ll need to install it manually:

Open Ubuntu via the Start Menu
Check if Homebrew is already installed:

[BASH]

brew --version

If you get a “command not found” error, proceed to the next step.

Install Homebrew:

[BASH]

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Verify the installation path:

[BASH]

whereis brew

Note: The default location is usually /home/linuxbrew/.linuxbrew/bin/brew

Python not installed or incorrect version

The ADK supports Python 3.11 to Python 3.13. It does not currently support Python 3.14 and forwards. Follow these steps to configure Python 3.12:

Open Ubuntu via the Start Menu.
Check if Python 3.12 is installed:

[BASH]

python3.12 --version

If not installed, continue with the steps below.

Install Python 3.12 using Homebrew:

[BASH]

brew install python@3.12

Set Python 3.12 as the default:

[BASH]

ln -s /home/linuxbrew/.linuxbrew/opt/python@3.12/bin/python3.12 /home/linuxbrew/.linuxbrew/opt/python@3.12/bin/python
ln -s /home/linuxbrew/.linuxbrew/opt/python@3.12/bin/pip3.12  /home/linuxbrew/.linuxbrew/opt/python@3.12/bin/pip
echo 'export PATH="/home/linuxbrew/.linuxbrew/opt/python@3.12/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Confirm the installation path:

[BASH]

whereis python3.12

Verify that Python 3.12 is now the default:

[BASH]

python --version

This should return the installed version of Python 3.12.

Managing connections for Python tools

There are many error messages that may occur when importing a Python tool with credentials (especially one with expected_credentials). Most serve to help guide the user in how to properly define their connections to work with their Python tool.

No app-id given

If no app-id is passed into a tool that has expected_credentials you see the following error:

[BASH]

[ERROR] - The tool 'my_sample_tool' requires an app-id 'my_app_id'. Please use the `--app-id` flag to provide the required app-id

To fix this, be sure to pass in the —app-id flag when importing the tool and make sure that the name is correct:

[BASH]

orchestrate tools import -k python -f <path to file> --app-id my_app_id

No connection exists

If you try to pass in a connection that doesn’t exist you see the following:

[BASH]

[ERROR] - No connection exists with the app-id 'my_app_id'

To fix this be sure that you create the connection before importing the tool:

[BASH]

orchestrate connections add --app-id my_sample_tool

Type Mismatch

If you specify an app id on a connection that is of a different type than what the tool specifies in expected_credentials you see the following:

[BASH]

[ERROR] - The app-id 'my_app_id' is of type 'basic_auth'. The tool 'my_sample_tool' expects this connection to be of type 'api_key_auth'. Use `orchestrate connections list` to view current connections and use `orchestrate connections add ` to create the relevant connection

To fix this remove the existing connection with that name and re-create it with the correct type. Or if that connection is used by a different tool that requires that type, create a new connection with a different name (my_app_id_2) and the correct type. Then import using an alias:

[BASH]

orchestrate tools import -k python -f <path to file> --app-id my_app_id=my_app_id_2

Release Notes

Get Started

Environments

Agents

Tools and Connections

Large Language Models (LLMs)

Knowledge Bases

Webchats

Tutorials

API's reference

Legal notices

Installing the watsonx Orchestrate Developer Edition

Managing connections for Python tools

Release Notes

Get Started

Environments

Agents

Tools and Connections

Large Language Models (LLMs)

Knowledge Bases

Webchats

Tutorials

API's reference

Legal notices

​Installing the watsonx Orchestrate Developer Edition

​Managing connections for Python tools

Installing the watsonx Orchestrate Developer Edition

Managing connections for Python tools