Release Notes
- What's new
- Known issues
- Troubleshooting
- License reference
Get Started
Environments
Large Language Models (LLMs)
Webchats
Tutorials
API's reference
- watsonx Orchestrate Developer Edition APIs
Troubleshooting
Installing the watsonx Orchestrate Developer Edition
When installing the watsonx Orchestrate Developer Edition, you might encounter some permission errors.
-
Try to log in manually with the following command:
Copydocker 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:
Copy{ "auths": { "us.icr.io": { "auth": "BASE64_ENCODED_APIKEY" } } }
Where
BASE64_ENCODED_APIKEY
is the base64 encoded string ofiamapikey:DOCKER_IAM_KEY
.
For Windows users, you might also encounter containerization issues as Windows systems do not support Docker natively.
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:
\\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.
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:
brew --version
If you get a “command not found” error, proceed to the next step.
- Install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- Verify the installation path:
whereis brew
/home/linuxbrew/.linuxbrew/bin/brew
To ensure compatibility, Python 3.11 to 3.13 should be installed and set as the default version. Follow these steps to configure the Python 3.12:
- Open Ubuntu via the Start Menu.
- Check if Python 3.12 is installed:
python3.12 --version
If not installed, continue with the steps below.
- Install Python 3.12 using Homebrew:
brew install python@3.12
- Set Python 3.12 as the default:
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:
whereis python3.12
- Verify that Python 3.12 is now the default:
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.
If no app-id is passed into a tool that has expected_credentials
you see the following error:
[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:
orchestrate tools import -k python -f <path to file> --app-id my_app_id
If you try to pass in a connection that doesn’t exist you see the following:
[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:
orchestrate connections add --app-id my_sample_tool
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:
[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:
orchestrate tools import -k python -f <path to file> --app-id my_app_id=my_app_id_2