Skip to main content
Version: 2.0 (Latest)

Troubleshooting + Common Issues

This page provides help for common issues with installing Loft.

Troubleshooting Tips

Flag --reset

If you need a clean Loft installation, you can use the --reset flag to tell Loft CLI to purge any previous Loft installs:

loft start --reset    # --insecure  ...add any other `loft start` flags if needed

Debug ImageErr + ImagePullBackOff

If your Loft pods are not starting because the Loft images cannot be pulled, you may need to use a private image registry rather than pulling Loft images from Docker Hub.

Use Port-Forwarding

You can always try to connect to Loft directly and circumvent any potential networking issues introduced at the load balancer and ingress controller level.

To start port-forwarding, either use loft start or run:

kubectl port-forward deploy/loft -n loft 8080:443

After that you can access Loft at https://localhost:8080. You can even login with the Loft CLI to this URL with:

loft login localhost:8080 --insecure

If you can access Loft via port-forwarding only, this is usually an indicator that the problem might be related to a misconfigured Load Balancer or Ingress Controller.

Air-Gapped / Offline / VPC Clusters

If your cluster is air-gapped, within a VPC or restricts network connectivity in other ways, you may need:

Offline License Key

If your cluster does not allow the Loft pod to connect the Loft license server, you have 2 options:

Allow requests to license.loft.sh (preferred)

To connect to the license server, you need to allow any HTTP requests from the Loft pod(s) to https://license.loft.sh/*.

Activate Loft with an Offline License Key

  1. Contact sales@loft.sh to purchase an offline license key or to request a trial license key

  2. Edit your existing loft.yaml file or create a new file named loft.yaml with content:

    env:
      LICENSE_KEY: "YOUR_LICENSE_KEY"

  3. Set the $VERSION variable to the Loft version you want to upgrade to OR set it to the current version using:

    CHART=$(kubectl get service loft -n loft -o jsonpath={.metadata.labels.chart})
    VERSION=${CHART:5}

  4. Upgrade Loft via:

    To upgrade Loft via Loft CLI, run:

    loft start --upgrade --version=$VERSION --values=loft.yaml

Offline Images

If your cluster is not able to pull images from Docker Hub, you have to push the Loft images into your private registry. To find out which images are required, we publish a file called loft-images.txt with each Loft release.

Follow these instructions to download all Loft ind import them to your private registry:

  1. Set the $VERSION variable to the Loft version you want to upgrade to OR set it to the current version using:

    CHART=$(kubectl get service loft -n loft -o jsonpath={.metadata.labels.chart})
    VERSION=${CHART:5}

  2. Set your private registry as variable:

    REGISTRY=ecr.io/myteam      # THIS SHOULD BE A PREFIX / DO NOT INCLUDE ANY LOFT_IMAGE PATHS

  3. Download the file loft-images.txt and the required scripts called download-images.sh and upload-images.sh:

    wget https://github.com/loft-sh/loft/releases/download/v${VERSION}/loft-images.txt
    wget https://github.com/loft-sh/loft/releases/download/v${VERSION}/download-images.sh
    wget https://github.com/loft-sh/loft/releases/download/v${VERSION}/upload-images.sh

    chmod +x ./download-images.sh
    ./download-images.sh --image-list loft-images.txt

  4. Make scripts download-images.sh and push-images.sh executable:

    chmod +x ./download-images.sh
    chmod +x ./push-images.sh

  5. Run download-images.sh to download all images locally:

    ./download-images.sh --image-list loft-images.txt

  6. Run push-images.sh to push all downloaded images to your private registry:

    ./push-images.sh --registry ${REGISTRY}

  7. Edit your existing loft.yaml file or create a new file named loft.yaml with content:

    image=${REGISTRY}/loftsh/loft:${VERSION}    # Replace ${REGISTRY} and ${VERSION}
    env:
      DEFAULT_IMAGE_REGISTRY: ${REGISTRY}       # Replace ${REGISTRY}

  8. Upgrade Loft via:

    To upgrade Loft via Loft CLI, run:

    loft start --upgrade --version=$VERSION --values=loft.yaml