Troubleshooting Guide 

Trying to run `make sdkbase` and seeing errors that include `TLS-enabled daemon` and/or `docker daemon`

When you try to run make sdkbase if you see a message like:

docker build -t kbase/kbase:sdkbase2.latest sdkbase
Post http:///var/run/docker.sock/v1.20/build?cgroupparent=&cpuperiod=0&cpuquota=0&cpusetcpus=&cpusetmems=&cpushares=0&dockerfile=Dockerfile&memory=0&memswap=0&rm=1&t=kbase%2Fkbase%3Asdkbase.latest&ulimits=null: dial unix /var/run/docker.sock: no such file or directory.
* Are you trying to connect to a TLS-enabled daemon without TLS?
* Is your docker daemon up and running?
make: *** [sdkbase] Error 1

You likely have not started your Docker daemon. On a Mac, that means running in the Docker CLI shell after starting Docker Kitematic and clicking on “Docker CLI” in the lower left corner (See Install SDK Dependencies - Docker for guidance).

My code keeps disappearing. What happened to it?

Magic comments are comments that are used internally by the kbase_sdk in order to generate the implementation file when you make changes to the spec file.

Examples of magic comments include:

#BEGIN_HEADER
# (This is where your import statements go)
#END_HEADER

#BEGIN_CLASS_HEADER
# (This is where your class variables and functions go that you want imported)
#END_CLASS_HEADER

#BEGIN_CONSTRUCTOR
# (This is in your init statement for your class goes)
#END_CONSTRUCTOR

#BEGIN YourFunctionName1
# (This is where the implementation details of your functions go)
#END YourFunctionName1

Any code created outside of the Magic Comments will not be included inside the final .impl implementation file.

Having trouble getting Docker working on Mac 

It may be that your Docker installation may be incorrect, out of date, or the daemon may not have been started. Please see https://docs.docker.com/mac/

Having trouble getting Docker working on Linux 

It may be that your Docker installation may be incorrect, out of date, or the daemon may not have been started. Please see https://docs.docker.com/linux/

My report isn’t generating output correctly 

See the guide on Creating a report .

Getting “ServerError: JSONRPCError”

Full error: ServerError: JSONRPCError: -32601. Unknown server error (output data wasn't produced)

This case happens because the python process exits without writing an output file, and then the callback server throws the above error. Make sure your process finishes and writes an output file to avoid this error.

Unable to find valid certification 

If you get an error on OSX as follows:

$ kb-sdk test
> Validating module in (/Users/user/Module/ExpressionUtils)
> Congrats- this module is valid.
> Error while testing module: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
> For more help and usage information, run:
>     kb-sdk help
>     (ExpressionUtils)

Reinstall the latest version of the KBase SDK

Follow instructions at https://kbase.github.io/kb_sdk_docs/tutorial/2_install.html
Don’t forget to generate the new kb-sdk executable

Alternatively, generate new security certificates:

$ openssl x509 -in <(openssl s_client -connect ci.kbase.us:443 -prexit 2>/dev/null) -out ~/example.crt
$ sudo keytool -importcert -file ~/example.crt -alias example -keystore $(/usr/libexec/java_home)/jre/lib/security/cacerts -storepass changeit

My Docker instances have run out of space 

Sometimes, an error message might indicate that you’re out of space. Run this check:

$ cd test_local
$ ./run_bash.sh
$ df -h

You can free up space by cleaning up containers, images, and volumes. If you end up needing a removed image or container, you can always download and recreate them later.

Remove stopped containers with docker container prune

Remove orphan images with docker image prune

Note

Don’t use the -a flag unless you want to blow away ALL KBase images and have to download them again

Remove local test images:

docker images | grep -e 'test/' -e 'none' | awk '{print $3}' | xargs docker rmi

If you encounter this error frequently, adjust how much disk space is allocated to docker in docker’s global preferences page (described in more detailed in the following section).

My Docker container ran out of memory 

This is perhaps the hardest to debug because it occurs during a run and dies (almost) silently. It will typically occur when handling (multiple) large workspace objects such as plant genomes. One way to figure out that it has happened is that the keyword “Killed” is printed.

If you suspect that your container is running out of memory, you may adjust your Docker resource settings to alleviate the problem.

Go to the global preferences for Docker and click on “Advanced”. There, you can increase the amount of memory available to the containers.

../_images/docker_advanced.png — Advanced preferences in Docker for OS X.

Error Messages and Solutions 

Error: `KeyError: 'getpwuid()' uid not found`

This error occurs when host user IDs (UIDs) do not match the container’s UIDs. The user ID is stored in your ~/.kbsdk.cache. Please clear out the cache with the command rm -rf ~/.kbsdk.cache and try again. Otherwise try the following:

Solution: Modify the UID in the test scripts 

Modify the following scripts in the test_local directory:

run_tests.sh
run_bash.sh
run_subjobs.sh

Change the user flag to --user 0 to run as root, which should bypass the UID issues:

Example, change ./run_tests.sh --user $(id -u) to ./run_tests.sh --user 0.

If the problem persists, consider removing the --user flag altogether.

Error: `Can't find image [test/<your_module_name>:latest]`

Error: "Can't find image [test/<your_module_name>:latest]
Here is 'docker images' output: Cannot connect to the Docker daemon.
Is the docker daemon running on this host?

This error indicates that Docker is either not running or not reachable, which prevents Docker commands from executing properly.

Solution: Fix Docker Daemon Socket Permissions 

Ensure that the Docker daemon is running on your host.

2. Modify the permissions of the Docker socket to allow group write access, which should resolve connection issues docker run -it -v /var/run/docker.sock:/var/run/docker.sock alpine chmod g+w /var/run/docker.sock

Clear your kb_sdk cache with the command rm -rf ~/.kbsdk.cache and try running your kb-sdk command again.

Error: client version 1.23 is too old.

Error response from daemon: client version 1.23 is too old.
Minimum supported API version is 1.24, please upgrade your client to a newer version

Solution: Downgrade to a supported Docker Desktop version 

kb-sdk is not supported on new Docker Desktop versions. If you encounter this error, downgrade your Docker Desktop to version 4.24.0 or lower.
Alternatively, you can use other Docker tools like Rancher Desktop, Podman, or Colima.