Troubleshooting

Last modified: 22 January 2025

A dev environment doesn't start, or the start takes too long

Symptoms

After you start a dev environment, the IDE doesn't open. If you go to CodeCanvas and check the dev environment status, you see that the dev environment is in the Starting: provisioning resources state. In the Timeline, you see the Resources provisioning takes longer than expected message.

Possible causes

There are several reasons why the dev environment might not start or take too long to start:

  • Problems with creating the dev environment volume – The problems related to the Kubernetes cluster infrastructure, e.g., an improperly configured CSI (Container Storage Interface) driver responsible for volume provisioning. Learn more

  • Insufficient resources – Dev environments fail to start because there are not enough resources available in the Kubernetes cluster. Learn more

  • Problems with pulling a Docker image – The Docker image required to start the dev environment can't be pulled from the registry. Learn more

Verification and solution

To troubleshoot the problem, you need to verify the possible causes first.

Volume issues

The issue is typically related to the Kubernetes cluster infrastructure or an improperly configured CSI (Container Storage Interface) driver responsible for volume provisioning.

To verify the issue

warning

The View debug data permission is required. By default, only the system administrators (the System Admin role) have this permission.

  1. In the header navigation, select Administration, then Dev Environments and find the dev environment that failed to start.

  2. Open the dev environment details and go to the Compute State tab.

  3. Open the Volume sub-tab and check the K8s Volume section for persistent volume claim events. If you see a message like:

    Waiting for a volume to be created either by the external provisioner
<provisioner name> or manually by the system administrator.
If volume creation is delayed, please verify that the provisioner
is running and correctly registered.

    and do not see a message like:

    Successfully provisioned volume <volume name>

    then the volume creation is not completed successfully.

To solve the issue

  1. Verify that the CSI driver is installed correctly and configured for your Kubernetes cluster.

  2. Examine the logs for the CSI provisioner for errors: 

    kubectl logs -n <namespace> <provisioner-pod-name>

    Look for error messages or warnings indicating configuration issues.

Insufficient resources

The Kubernetes cluster doesn't have enough free resources to accommodate the dev environment pod. Common scenarios include:

  • All nodes are at capacity.

  • Nodes are incorrectly sized.

  • Kubernetes system components (for example, kubelet, kube-proxy) are consuming node resources, reducing available capacity for user workloads.

To verify the issue

warning

The View debug data permission is required. By default, only the system administrators (the System Admin role) have this permission.

  1. In the header navigation, select Administration, then Dev Environments and find the dev environment that failed to start.

  2. Open the dev environment details and go to the Compute State tab.

  3. Open the Worker sub-tab and check the K8s Pod Data section. If you see a message like: 

    0/[n] nodes available: insufficient [resource]

    and do not see a message like:

    Successfully assigned <pod name> to <node name>

    then the pod can't be scheduled onto a node due to insufficient resources (e.g., CPU, memory, storage).

To solve the issue

  • Try one of the following solutions:

    • Set up node autoscaling. See our recommendations.

    • Provision nodes manually – add appropriately-sized nodes to the Kubernetes cluster to meet the resource requirements of the dev environment.

    • Free up resources on existing nodes.

    • Verify node resource usage – Keep in mind that Kubernetes reserves some resources on nodes for system components. Ensure the nodes have additional free capacity beyond what's required by the user workloads.

    • Refer to the additional troubleshooting resources.

Image pull issues

Dev environments fail to start because the container image can't be pulled from the registry:

  • The specified image doesn't exist in the registry.

  • Incorrect or missing pull credentials (e.g., private registry authentication failure).

  • Network or connectivity issues between the Kubernetes cluster and the registry.

To verify the issue

  1. In the header navigation, select Administration, then Dev Environments and find the dev environment that failed to start.

  2. Open the dev environment details and go to the Compute State tab.

  3. Open the Worker sub-tab and check the K8s Pod Data section. If you see a message like: 

    Failed to pull image <image name>

    or 

    Error: ErrImagePull

    or 

    Error: ImagePullBackOff

    and do not see a message like:

    Pulled

    then the image can't be pulled from the registry.

To solve the issue

  • Try one of the following solutions:

    • Verify the image name and tag and confirm that the image exists in the registry.

    • Check the pull credentials – If the image is in a private registry, make sure you provided the correct credentials.

    • Check registry access – Ensure that the Kubernetes cluster has network connectivity to the registry.

    • Refer to the additional troubleshooting resources.