Troubleshooting

I’m Getting a Timeout Error

Depending on the connection and resources, the installation process may time out. If that occurs, use the --wait-duration flag to provide additional time. The time must be provided in Go duration format (for example: 60s, 1m, etc). The following example extends the wait duration to 10 minutes:

kubectl kots install wallaroo/ea -n wallaroo --license-file myfile.yaml --shared-password wallaroo --wait-duration 600s

Preflight Checks are Failing at the Command Line

If your system does not meet all of the preflight requirements, the installation process may fail when performing an automated installation. It is highly recommended to install Wallaroo on a system that meets all requirements or else performance will be degraded.

Before continuing, use the following command and note down any and all pre-flight checks that are listed as a failure. The license will be installed in later steps through the browser.

install wallaroo/ea -n wallaroo

To ignore preflight checks, use the --skip-preflights flag, as in the following example (Note: This is not recommended, only provided as an example.):

kubectl kots install wallaroo/ea -n wallaroo --license-file myfile.yaml --shared-password wallaroo --skip-preflights

When Launching JupyterHub, I get a Server 500 error

If you shut down and restart a Wallaroo instance in a new environment or change the IP address, some settings may not be updated. Run the following command to restart the deployment process and update the settings to match the current environment. Note that the namespace wallaroo is used - modify this to match the environment where Wallaroo is installed.

kubectl rollout restart deployment hub -n wallaroo

The resource wallaroo/daemonset/spire-agent shows as not loading - how do I fix it?

If the resource wallaroo/daemonset/spire-agent does not load, verify the kots version is 1.124.4. To upgrade the kots version in your Kubernetes cluster, see see Updating KOTS.

Usually this can be done by:

1. Updating the version of kots with the command:

   curl https://kots.io/install/1.124.4 | REPL_USE_SUDO=y bash
   

2. Upgrade kots in the Kubernetes cluster with the following, replacing the namespace wallaroo with the namespace you have installed the Wallaroo Ops instance in:

   kubectl kots admin-console upgrade --namespace wallaroo
   

How do I Send Logs and Configurations to Wallaroo?

See the Wallaroo Support Bundle Generation Guide for instructions on how to create a support bundle used to troubleshoot installation and configuration issues.

How do I Fix a Stuck Upgrade?

When doing an upgrade of Wallaroo and access the Wallaroo instance via a browser, the following message indicates a “stuck” upgrade when it remains after the upgrade process is complete:

• Wallaroo upgrade in progress

Use the following procedures to clear the upgrade stream based on how Wallaroo was installed.

Cluster Install

For a cluster based install of Wallaroo, enter the following command, replacing $NAMESPACE with the namespace associated with the Wallaroo install:

kubectl run -i --rm --tty nats-box --restart=Never -n $NAMESPACE --image=natsio/nats-box

For example, for the namespace wallaroo this command is:

kubectl run -i --rm --tty nats-box --restart=Never -n wallaroo --image=natsio/nats-box

In a separate terminal shell, enter the following command:

nats -s nats stream purge wallaroo_upgrade_status

Air-Gapped Install

For air-gapped installations of Wallaroo, determine the private image registry with the following command. This returns the running pod that is the issue.

kubectl describe deployment dashboard|grep Image

The following is an example of the response from this command:

Image:      abcdefg.dkr.ecr.us-east-2.amazonaws.com/wallaroo/dashboard:v2025.1.0-main-6081

For this example, the registry here is abcdefg.dkr.ecr.us-east-2.amazonaws.com/wallaroo/.

Enter the following command, replacing the image value with the pod returned in the previous command:

kubectl run -i --rm --tty nats-box --restart=Never -n wallaroo --image=abcdefg.dkr.ecr.us-east-2.amazonaws.com/wallaroo/nats-box:0.17.0-nonroot

Failed Deploy Status When Attempting to Upgrade

If a “Failed Deploy" message is shown in kots or helm, retrieve the pods to check for a stalled pre-upgrade hook. Replace the $NAMESPACE variable with the namespace used to install Wallaroo.

kubectl get pods -n $NAMESPACE

For example, for the namespace wallaroo the command is:

kubectl get pod -n wallaroo

If the pre-upgrade hook still shows Running under STATUS the following command will remove the pod so the upgrade can be attempted again. Replace the $NAMESPACE variable with the namespace used to install Wallaroo.

kubectl delete job wallaroo-pre-upgrade-hook -n $NAMESPACE

For example, for the namespace wallaroo the command is:

kubectl delete job wallaroo-pre-upgrade-hook -n wallaroo

How to Resolve the Message “failed to render archive directory” for Single Node Linux Installations

If the error failed to render archive directory appears during an installation of Single Node Installation or Air-Gapped Single Node installation, this may indicate the incorrect ingress mode was selected during the installation process.

Verify that Ingress mode is Embedded: