Skip to content


Below is a list of FAQs and common issues that may help you while using KraftCloud.

Why does my (large) filesystem build process get stuck?

In case of filesystems larger than about 800MB, the build may get stuck. The issue is caused by a problem in BuildKit, the current filesystem build component used by KraftCloud.

The current workaround is to reduce the filesystem image below 800 MB; we are working to integrate another filesystem build component that gets past the BuildKit limitation.

I have a problem with my app, how do I debug it?

Your application may crash, freeze or misbehave. Typically you use kraft cloud inst logs <instance_name> or kraft cloud inst get <instance_name> to inspect. This may, in certain times, provide insufficient information.

For more extensive information, use the debug builds of images. See details in the “Debugging Applications” guide.

I’m getting a gateway error, what gives?

When you query a KraftCloud service via its public URL, such as below:

Terminal window

you may get a Bad Gateway response:

<head><title>502 Bad Gateway</title></head>
<center><h1>502 Bad Gateway</h1></center>

This is the case when you specify the wrong internal application port when deploying, for example if the application exposes port 8080 but you happen to use 443:80 instead of 443:8080.

Another error response you may get is:

<!doctype html>
<html lang="en">
<meta charset="UTF-8">
<meta name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Service not found</title>
There is no service on this URL.

This typically happens when you connect to your app with an HTTPS client (on port 443) and the application doesn’t expose that port externally. This is the case with database services such as MongoDB or MariaDB that use a different protocol/port (e.g., 27017, 3306).

To solve this, use the appropriate exposed port; this may require the use of TLS tunnel, as detailed below.

How do I connect to a non-TLS App?

KraftCloud uses TLS to expose services to the outside world. However, certain applications (such as MongoDB or MariaDB) do not use TLS. In these cases, you can create a TLS tunnel via the kraft cloud tunnel, which will open a local end point (on localhost / that will tunnel the client traffic via the TLS tunnel. For an example of this please refer to the MariaDB guide.

I’m getting a “no such file or directory” when building/deploying an image

When building / deploying an image, you may get the error below:

E unpacking the image: opening layer: open <path_to_home_directory>/.local/share/kraftkit/runtime/oci/digests/sha256/3d30a7ba2a819aec2e73c5df07c24264d66891e926b395b9ef0f66f151db4b49: no such file or directory

Generally, this means that the local kraft cache is in an inconsistent state.

To solve this, remove the local kraft cache and local packages:

Terminal window
kraft pkg rm --all
rm -fr ~/.local/share/kraftkit

I’ve launched an app but I can’t see it/list it

The most common reason is when you (and us too!) deploy an app to one metro but do a listing on a different one. To set the metro you use, you can do it for a session by an env variable:

Terminal window
export KRAFTCLOUD_METRO=<metro_name>

or for each indvidual command via the --metro flag, for example:

Terminal window
kraft cloud instance list --metro <metro_name>

How can I cache the app’s filesystem for faster builds?

When using a Dockerfile for the application filesystem, the commands are passed to BuildKit.

By default, an ephemeral BuildKit container is started each time you invoke kraft cloud deploy. This means that the filesystem application data is then removed, and that each deploy command will start from zero.

To prevent this, follow the instructions here:

Terminal window
docker run -d --name buildkitd --privileged moby/buildkit:latest
export KRAFTKIT_BUILDKIT_HOST=docker-container://buildkitd