FAQ - Server Setup

Troubleshooting common issues when setting up KDB.AI Server. For initial setup steps, see KDB.AI Server Setup.

Docker registry and authentication

Q: I'm getting "unauthorized" or "access denied" when pulling the Docker image.

Verify you're using the email address you signed in to portal.dl.kx.com with.
Check that your bearer token was generated via Token Management (click your username in the top right of the portal, then + Add New Token). Note that tokens are disabled 90 days after your last interactive login.

Check the login command format:

docker login portal.dl.kx.com -u <your-portal-email> -p <your-bearer-token>

Common mistakes:
- Using a truncated bearer token — copy the entire string.
- Using a different email than the one you signed in to the portal with.

Q: Docker login succeeds but I still can't pull the image.

Try pulling the image explicitly:
```
docker pull portal.dl.kx.com/kdbai-db
```

Clear Docker credentials and re-login:

docker logout portal.dl.kx.com
docker login portal.dl.kx.com -u <email> -p <token>

License issues

Q: I'm getting a "license error" or the container won't start due to license issues.

Ensure you are using a KDB.AI-compatible license:
- Community license: Obtained by installing kdb-x. The license is installed at $HOME/.kx/kc.lic by default.
- Commercial (K4) license: Contact support@kdb.ai.
Using a plain kdb+ license with KDB.AI Server will result in the error: Sorry, looks like the license you supplied is not compatible with KDB.AI. You must use a kdb-x license.

Verify the license encoding:

export KDB_LICENSE_B64=$(base64 -w 0 $HOME/.kx/kc.lic)
echo $KDB_LICENSE_B64

The output should be a long base64-encoded string.

Common license errors:
- Incompatible license: You are using a kdb+ license instead of a KDB.AI license. See step 1 above.
- File not found: Check the path to your kc.lic file.
- Invalid encoding: Ensure you're using base64 -w 0 (no line wrapping).
- Variable not picked up when using sudo: Pass environment variables explicitly with sudo -E docker run ....

Container startup and connectivity

Q: My container starts but health checks fail.

Confirm the container is running:
```
docker ps
```
Test the health endpoint:
```
curl http://localhost:8081/api/v2/ready
```
Expected response: OK
Check container logs:
```
docker logs <container-name>
```

Run without -d to see real-time logs:

docker run \
  -p 8081:8081 \
  -p 8082:8082 \
  -e KDB_LICENSE_B64=$KDB_LICENSE_B64 \
  -v "$PWD/vdbdata":/tmp/kx/data \
  -e THREADS="8" \
  portal.dl.kx.com/kdbai-db

Q: The container starts but I can't connect from the Python client.

Check the server's required client version range:

curl http://localhost:8081/api/v2/version
# example response: {"serverVersion":"latest","clientMinVersion":"2.0.0","clientMaxVersion":"latest"}

Then verify your installed client version meets the requirement:

pip show kdbai-client

If it is outside the supported range, upgrade:

pip install kdbai-client --upgrade

Test the connection:

import kdbai_client as kdbai
session = kdbai.Session(endpoint='http://localhost:8082')
database = session.database('default')
print(database.tables)  # Should return []

Check ports are exposed:
```
docker container port <container-name>
```
Verify firewall settings aren't blocking ports 8081 and 8082.

Volume mounting and permissions

Q: I'm getting permission denied errors when the container tries to write data.

Create the data directory with proper permissions:
```
mkdir vdbdata
chmod 0777 vdbdata
```
On Windows, run the setup from within WSL and ensure your data directory is on a Linux filesystem (ext4) within WSL.

Q: My container starts but data is not being persisted.

Verify the mount path in your docker run command:
```
-v "$PWD/vdbdata":/tmp/kx/data
```
Ensure you're running the command from the directory where vdbdata exists.
Check whether the container is writing to the mounted volume:
```
docker exec <container-name> ls -la /tmp/kx/data
```

Q: I'm on macOS and getting volume mount errors.

Rancher DesktopDocker Desktop

Go to Preferences > Virtual Machine > Volumes tab.
Select virtiofs as the mount type.

Go to Docker Desktop Settings > Resources > File Sharing.
Add your project directory to the list.

Threading configuration

Q: How should I configure the THREADS environment variable?

Set THREADS to match your available CPU cores:

nproc              # Linux / WSL
sysctl -n hw.ncpu  # macOS

Then pass it in the docker run command:

-e THREADS="<number-of-cores>"

For systems with more than 24 cores, also use --cpuset-cpus 1-24.

Still stuck?

For general questions, ask the Slack community.

For issues requiring investigation, email support@kdb.ai and include:

Container logs:

docker logs <container-name> > yourDocker.log 2>&1

System information:
- OS and version
- Docker version: docker --version
- CPU architecture: uname -m
- Available cores: nproc
The exact error messages you're seeing.