Troubleshooting, reporting bugs, and common issues
Tutorial
When encountering build errors, it is important to know how to approach fixing them. In this tutorial, we will explore practical ways to troubleshoot issues in custom image builds, ask for help with issues, and report bugs with BlueBuild to the maintainers.
Logs
If the issue happened during the build in GitHub Actions, the first step is always to look at the build logs. We can find the logs in the “Actions”-tab of the GitHub repository by pressing the failing build, and opening a specific failing build from the job matrix. 99% of errors will happen under the “Build Custom Image” step of the job, which has a long and verbose log of the pre-build set up and the image build itself. The builds stop at any error, so to find the error from the long log file, we can utilize the scroll bar to quickly get to the bottom of the log.
For a faster feedback loop when iterating on bugs, we can utilize local builds.
Getting help
If the problem is something we cannot figure out on our own, the BlueBuild community is here to help. See the community page for links to join the communities and some ground rules to follow. The most effective page to ask for help is the support category in the GitHub Discussions, as problems posted there show up on search engines. We might even find a fix to our problem there!
When asking for help, it is important that we provide enough information for a community member to start investigating the problem. This might make the difference between getting a response and being ignored.
When asking for help with an issue, we should provide a link to the affected repository, the logs that show the problem we encountered, and what we’ve already done in terms of troubleshooting.
- Example
- Bad: Issue with recipe akmods. I’m trying to install an akmod but it doesn’t work.
- Good: Issue with the akmods module:
error: Packages not found: Nvidia. Here’s my repository: [link]. Here are the logs: [link].
When asking for help with implementing a new thing, we should outline requirements clearly, and ask about what we are actually trying to do instead of what we assume is the correct way to do it.
- Example
- Bad: How can I use a script to install something?
- Good: How can I install a custom kernel? I heard a that a script might be needed, but I’m not sure how to use that. I am trying to install the Zen kernel.
Common issues
This section contains short how-tos for fixing common issues.
error: Creating importer: Failed to invoke skopeo proxy method OpenImage: remote error: unable to retrieve auth token: invalid username/password: unauthorized
This error happens when the image you are trying to rebase to is private. This is currently the default state of a newly created package on GitHub. This is the result of a recent change, and the issue has been reported to GitHub. If this is your own image, you can fix this easily with the steps below.
- Go to the “Packages” tab on your GitHub profile.
- Choose the package you are trying to build.
- Open “Package settings”.
- Under “Danger Zone”, change the package visibility to “Public”.
- Manually re-trigger the build.
ghcr.io: denied: permission_denied: write_package
If you’re trying to build an image with the same name as something you’ve already built from a new repository, you might get this GitHub permission error. This happens because the GitHub package entry was created by the other repository, which is now attached to it.
To fix this issue:
- Go to the “Packages” tab on your GitHub profile.
- Choose the package you are trying to build.
- Open “Package settings”.
- Under “Manage Actions access”, add your new repository and give it the “Admin” role.
- Manually re-trigger the build.
https://diataxis.fr/tutorials/
- opening logs
- interacting with community
- all kinds of experience reports are valuable
- reporting bugs
- what sorts of clues to look for in logs
- common issues
ghcr.io: denied: permission_denied: write_package- what else?