Troubleshooting apko Builds

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

Make sure you’ve added the relevant package repositories you need and the package name is correct. Check the Wolfi repository for available packages if you are building Wolfi images, or the Alpine APK index if you are using Alpine as base.

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.