Troubleshooting apko Builds

Debugging and common errors

By Erika Heidi

Debug Options

To include debug-level information on apko builds, add --debug to your build command:

docker run --rm -v ${PWD}:/work cgr.dev/chainguard/apko build --debug \
  apko.yaml hello-minicli:test hello-minicli.tar \
  -k melange.rsa.pub

Common Errors

When the apk package manager is unable to resolve your requirements to a set of installable packages, you will get an error similar to this:

There are two main root causes for this error, which we’ll explain in more detail in the upcoming section:

  • apk cannot find the package in the included repositories, or
  • apk cannot find the apk index for your custom-built packages.

The requested package is not in the included repositories

For Alpine packages, make sure you’ve added the relevant package repositories you need and the package name is correct — search the Alpine APK index for reference.

If this is your case, you should find error messages similar to this when enabling debug info with the --debug flag:

apko is unable to find the local packages folder

With melange-built package(s), make sure you have a volume sharing your apko / melange files with the location /work inside the apko container.

The apk index is missing

If you have a functional volume sharing your packages with the apko container and you’re still getting this error, make sure you built a valid apk index as described in step 4 of the Getting Started with melange Guide.

If this is your case, you should find error messages similar to this when enabling debug info with the --debug flag:

This is how your packages directory tree should be set up, including the APKINDEX.tgz file for each architecture:

packages
├── aarch64
│   ├── APKINDEX.tar.gz
│   └── hello-minicli-0.1.0-r0.apk
├── armv7
│   ├── APKINDEX.tar.gz
│   └── hello-minicli-0.1.0-r0.apk
├── x86
│   ├── APKINDEX.tar.gz
│   └── hello-minicli-0.1.0-r0.apk
└── x86_64
    ├── APKINDEX.tar.gz
    └── hello-minicli-0.1.0-r0.apk

4 directories, 8 files

Further Resources

For additional guidance, please refer to the apko repository on GitHub, where you can find more examples or open an issue in case of problems.