Unable to preload and image now?

For some reason I’ve been able to preload imgs but now it’s not working?

Here is my command:
balena preload balena.img --app APPID --api-token "APITOKEN" --img ~/downloads/balena.img

The results:

[debug] original argv0="/usr/local/lib/balena-cli/bin/node" argv=[/usr/local/lib/balena-cli/bin/node,/usr/local/lib/balena-cli/bin/run,preload,balena.img,--app,1535609,--api-token,APITOKEN,--img,/Users/Name/downloads/balena.img] length=10
Building Docker preloader image. [===                     ] 12%
Step 1/7 : FROM docker:17.10.0-ce-dind
Building Docker preloader image. [======                  ] 25%
Step 2/7 : RUN apk update && apk add --no-cache python3 parted btrfs-progs docker util-linux sfdisk file coreutils sgdisk
 ---> Using cache
Building Docker preloader image. [=========               ] 37%
Step 3/7 : COPY ./requirements.txt /tmp/
 ---> Using cache
Building Docker preloader image. [============            ] 50%
Step 4/7 : RUN pip3 install -r /tmp/requirements.txt
 ---> Using cache
Building Docker preloader image. [===============         ] 62%
Step 5/7 : COPY ./src /usr/src/app
 ---> Using cache
Building Docker preloader image. [==================      ] 75%
Step 6/7 : WORKDIR /usr/src/app
 ---> Using cache
Building Docker preloader image. [=====================   ] 87%
Step 7/7 : CMD ["python3", "/usr/src/app/preload.py"]
 ---> Using cache
 ---> de892f8dbc61
Successfully built de892f8dbc61
Building Docker preloader image. [========================] 100%

But it never actually shows up on the folder or anywhere for that matter.

@KingstonSteele, given the command-line options you shared (especially --api-token and --img), I guess that in the past you were using the following balena-preload script directly:

… as opposed to using the balena CLI:

$ balena help preload
Usage: preload <image>

Warning: "balena preload" requires Docker to be correctly installed in
your shell environment. For more information (including Windows support)
please check the README here: https://github.com/balena-io/balena-cli .

Use this command to preload an application to a local disk image (or
Edison zip archive) with a built release from balena.


	$ balena preload balena.img --app 1234 --commit e1f2592fc6ee949e68756d4f4a48e49bff8d72a0 --splash-image image.png
	$ balena preload balena.img


    --add-certificate <certificate.crt>  Add the given certificate (in PEM format) to /etc/ssl/certs in the preloading container. The file name must end with '.crt' and must not be already contained in the preloader's /etc/ssl/certs folder. Can be repeated to add multiple certificates.
    --app, -a <appId>                    id of the application to preload
    --ca <ca>                            Docker host TLS certificate authority file
    --cert <cert>                        Docker host TLS certificate file
    --commit, -c <hash>                  The commit hash for a specific application release to preload, use "current" to specify the current release (ignored if no appId is given). The current release is usually also the latest, but can be manually pinned using https://github.com/balena-io-projects/staged-releases .
    --docker, -P <docker>                Path to a local docker socket (e.g. /var/run/docker.sock)
    --dockerHost, -h <dockerHost>        Docker daemon hostname or IP address (dev machine or balena device)
    --dockerPort <dockerPort>            Docker daemon TCP port number (hint: 2375 for balena devices)
    --dont-check-arch                    Disables check for matching architecture in image and application
    --key <key>                          Docker host TLS key file
    --pin-device-to-release, -p          Pin the preloaded device to the preloaded release on provision
    --splash-image, -s <splashImage.png> path to a png image to replace the splash screen

I suggest you try using the balena CLI with the command-line options described above. Or if necessary, try the old balena-preload script.

Also, what exactly do you mean by “it never shows up on the folder”?

What I mean is that the image I’m trying to download to be used to flash the SD card directly, is never actually downloaded anywhere on my machine. It says it’s built but it never actually shows up anywhere.

OK. My understanding, hoping to help: the balena preload command does not download an image, it uses a previously downloaded image. The balena os download command can be used to download images, before running balena preload. Or the image can be downloaded using the web dashboard (“add device” workflow).

Oh - maybe you and I were thinking of different images. Sorry for the confusion. The logs you shared in your first message are for the docker preloader image, which you might be able to see with the docker images command. The preloader image is not the balenaOS image that will be flashed. The preloader image is used to run some code (Python library) that implements part of the balena preload command, which preloads an application in a balenaOS image. In my previous message, when I said that balena preload does not download an image, I was thinking about a balenaOS image, rather than the preloader image. It’s confusing enough! :slight_smile:

Hey yeah what I’m trying to do is build an balenaOS image with the application on it so that I can just flash to an SD and have the application working without the Pi having to download the application.

Right. The balena preload command is supposed to do that. I’ve tested it here, in my case using macOS and CLI version 11.17.2, and fewer command-line options:

$ balena preload ~/Downloads/dev-test-rpi-raspberrypi3-2.32.0+rev1-dev-v9.14.0.img --app 1301645 --commit bbe58d4c9e0963bfa1203a37ba95ba54
Building Docker preloader image. [========================] 100%

/ Creating preloader container
| Starting preloader container
- Fetching application 1301645
\ Reading image information
This application is set to automatically update all devices to the current version.
This might be unexpected behaviour: with this enabled, the preloaded device will still
download and install the current release once it is online.

Do you want to disable automatic updates for this application?

Warning: To re-enable this requires direct api calls,
see https://balena.io/docs/reference/api/resources/device/#set-device-to-release

Alternatively you can pass the --pin-device-to-release flag to pin only this device to the selected release. No
\ Resizing partitions and waiting for dockerd to start
Pulling 3 images [========================] 100%
/ Cleaning up temporary files

Where / how does it fail for you? Is it getting stuck at the Building Docker preloader image stage? Could you share the balena CLI version and operating system version, so I could try to reproduce it more accurately?

My balenaOS version is 11.17.2 and my local machine is MacOS.

If I run your exact command:

balena preload ~/Downloads/dev-test-rpi-raspberrypi3-2.32.0+rev1-dev-v9.14.0.img --app 1301645 --commit bbe58d4c9e0963bfa1203a37ba95ba54

It gives me this as a result. No file is downloaded.

 ~/Downloads/dev-test-rpi-raspberrypi3-2.32.0+rev1-dev-v9.14.0.img --app 1301645 --commit bbe58d4c9e0963bfa1203a37ba95ba54
Building Docker preloader image. [========================] 100%

The image must be a read/write accessible file

Additional information may be available by setting a DEBUG=1 environment
variable: "set DEBUG=1" on a Windows command prompt, or "export DEBUG=1"
on Linux or macOS.

If you need help, don't hesitate in contacting our support forums at

For bug reports or feature requests, have a look at the GitHub issues or
create a new one at: https://github.com/balena-io/balena-cli/issues/

And if I use my own application, it gives the same kind of message/result.

My balena CLI version is 11.17.2 and my local machine is MacOS.

Same as mine! :slight_smile:
My macOS version is 10.14.6, though I don’t expect it matters.

No file is downloaded.

Probably because the preloader image (not the balenaOS image) had already been downloaded and cached. You may be able to see it with the "docker images" command:

$ docker images
REPOSITORY               TAG        IMAGE ID        CREATED         SIZE
balena/balena-preload    latest     3650d23de149    4 hours ago     279MB

The image must be a read/write accessible file

This error means that the balenaOS image given as argument to the balena preload command could not be read or written. This would be the image file "balena.img" in the following command line:

balena preload balena.img --app 1301645 --commit bbe58d4c9e0963bfa1203a37ba95ba54

Or the image file "~/Downloads/dev-test-rpi-raspberrypi3-2.32.0+rev1-dev-v9.14.0.img" in the following command line:

balena preload ~/Downloads/dev-test-rpi-raspberrypi3-2.32.0+rev1-dev-v9.14.0.img --app 1301645 --commit bbe58d4c9e0963bfa1203a37ba95ba54

Check that the given balenaOS image file exists, and has read/write permissions.

REPOSITORY              TAG                 IMAGE ID            CREATED             SIZE
balena/balena-preload   latest              de892f8dbc61        32 hours ago        279MB
docker                  17.10.0-ce-dind     9769e0f3f9cb        24 months ago       110MB

So given that it is cached, how would I make it accessible and able to be downloaded? What’s the next step?

The objective of the balena preload command is to load (preload) a balena application in a balenaOS image file such as "balena.img". The balenaOS image file (balena.img) can then be flashed to a SD card, for example using balenaEtcher or the balena local flash command.

The balena.img file (a balenaOS image that will be flashed to a SD card) must preexist before running the balena preload command. It will not be downloaded or created by the balena preload command. Rather, it will be modified by the balena preload command: a balena application will be inserted inside the balena.img file. It does not need to be named balena.img: it can be any other name you choose. A path to this file is given as the first command-line argument to the balena preload command.

The balena/balena-preload Docker image, that can be listed with the docker images command, is not the balenaOS image that will be preloaded and then flashed. Rather, the balena/balena-preload Docker image contains some code that is executed by the balena CLI as part of the implementation of the balena preload functionality. The balena/balena-preload Docker image will not show up as a file in some folder. (Well, it is stored somewhere in the hard disk, but it should not be focus of attention.)

What’s the next step?

I think the next step is to fix the error you were getting: “The image must be a read/write accessible file.” I understand that this error means that the balena.img file (given as argument to the balena preload command) could not be found: perhaps did not exist, or possibly did not have read/write permissions. Make sure that the balena.img file (or any other name you choose to give it) exists before running the balena preload command.

If you don’t have a pre-existing balenaOS image file (e.g. balena.img), you can download one through the balena application web dashboard (“add device” workflow), or using the balena os download command.

1 Like

I vastly misunderstood balena preload then but this works great. So what I need and what I’ve done is have a balena cloud image to begin with and then when I do the preload command, point it to where that image is. I was mistaken in thinking the img was downloaded as an img but instead what happens is that there is an img on you local system and preload modifies that. Same effect as downloading an img except that it’s faster since you don’t download EVERYTHING every time you make a change. Am I understanding this correctly?

Hey there. Yes, that is accurate.

1 Like