Troubleshooting FAQs
NOTE: first, you may want to confirm that you can build your Dockerfile locally and if so, then move on to the following Velocity-specific troubleshooting steps as needed.
Docker builds can fail for any number of reasons, but Velocity-specific causes may be that the filepath to your Dockerfile or build context (i.e., the directory from which you would run the Docker build command locally) in the run configuration are incorrect. Check that the filepath to both the Dockerfile and the build context align with your current application.
If the above paths are correct, double check the accuracy the following elements if they are included in your Docker build process:
- Build arg(s)
- SSH key(s)
- Secret(s)
Velocity leverages advanced caching to speed up container image build times. Sometimes this caching will prevent packages that have been added during a Velocity session to be added to the remote container.
You can click the Code Sync button
to override Velocity's caching, and rebuild your remote image from scratch based on your local source code.

Velocity uses your Kubeconfig file to populate options in the Kubernetes context dropdown. This file is located by default at
/.kube/config
. Alternatively, a non-default filepath to your Kubeconfig can be set with the environment variable KUBECONFIG
. To confirm that the Kubeconfig is accessible, you can run the following in a terminal window:
cat ~/.kube/config
or cat $KUBECONFIG
. If the file is accessible, you will see its contents printed to the terminal.Velocity requires the same cluster access as
kubectl
. If the Kubernetes namespace and workload fields aren't being populated when you create a Velocity run configuration, you may not have system-wide access to the cluster from your local machine, or you may not have permission to access a given namespace within the cluster. To confirm that you have system-wide access from your local machine to your cluster, open a new terminal window and run
kubectl get all -n <namespace>
. If you don't see output that is similar to the following, you likely need to re-authenticate for Velocity to access your cluster environment, or you don't have permission to access the specified namespace.NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 4d1h
Velocity's build process can be impacted by the size of your Docker image and your internet connection speed. If your build process is taking longer than expected, you may want to look at optimizing your Docker image, and confirming that your internet connection is stable.
Last modified 20h ago