Mastodon Skip to content
BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak. BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak. BlueBuild

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.

no space left on device

This error happens when the GitHub builder has ran out of space, and can surface during any operation that writes to the disk. Most commonly, the error will happen while committing the container. (Error: committing container for step, writing blob: storing blob to file, no space left on device)

You are more likely to encounter this issue when building on an already heavy image like Bazzite.

This issue can usually be fixed by setting maximize_build_space: true in the options of the BlueBuild GitHub Action, which is the default as of blue-build/[email protected]. GitHub organizations on paid plans can also take advantage of GitHub’s larger workflow runners.

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:

  1. Go to the “Packages” tab on your GitHub profile.
  2. Choose the package you are trying to build.
  3. Open “Package settings”.
  4. Under “Manage Actions access”, add your new repository and give it the “Admin” role.
  5. Manually re-trigger the build.

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. If this is your own image, you can fix this easily with the steps below.

  1. Go to the “Packages” tab on your GitHub profile.
  2. Choose the package you are trying to build.
  3. Open “Package settings”.
  4. Under “Danger Zone”, change the package visibility to “Public”.
  5. 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?