Dosu LogoDosu Logo
Ask
Join our Discord
Organization avatar
bluefinPublic
Bluefin
Documentsbluefin
PITFALLS
PITFALLS
Type
External
Status
Published
Created
Jun 13, 2026
Updated
Aug 1, 2026
Updated by
Dosu Bot
Source
docs/skills/PITFALLS.md

bootc-installer Pitfalls Reference#

Distilled engineering gotchas for projectbluefin/bootc-installer.
Load when debugging test failures, import errors, or GTK/GIO issues.


GTK Unit Testing Without a Display#

The __new__ + attribute injection pattern#

GTK subclasses (Adw.Bin, Adw.ActionRow, etc.) call Gtk.Template machinery in __init__, which requires a display. Bypass with:

obj = MyClass.__new__(MyClass)
obj._MyClass__private_attr = value # Python name-mangling for private attrs
obj.some_child_widget = MagicMock() # mock Template.Child() widgets

Building gi stubs#

Every test file that imports GTK code must stub gi.repository.* before importing. The canonical pattern:

def _build_gi_stubs():
    gi_mod = types.ModuleType("gi")
    gi_mod.require_version = MagicMock()
    repo = types.ModuleType("gi.repository")
    # ... stub Gtk, Adw, GLib, Gio, etc.
    sys.modules.update({"gi": gi_mod, "gi.repository": repo, ...})

def _import_MyClass_fresh():
    _build_gi_stubs() # ALWAYS call first
    pkg = sys.modules.get("bootc_installer.defaults")
    if pkg and hasattr(pkg, "mymodule"):
        delattr(pkg, "mymodule") # clear stale attribute cache
    sys.modules.pop("bootc_installer.defaults.mymodule", None)
    return importlib.import_module("bootc_installer.defaults.mymodule")

Rules:

  • Call _build_gi_stubs() INSIDE _import_X_fresh(), not once at module level
  • Pop both sys.modules[full.path] AND delattr(parent_pkg, "module") — Python caches module attributes separately from sys.modules
  • Use importlib.import_module() not bare import after clearing sys.modules

gi stub cross-contamination#

When multiple test files each call _build_gi_stubs() at module level, pytest's alphabetical collection order determines which stub wins. test_builder.py runs early and loads the real GTK C-extensions via bootc_installer.utils.builder. Any test file that runs after it and calls patch("...Gio.some_method") may be patching the real C object — the patch silently fails.

Symptom: Test passes when run alone, fails in the full suite.
Diagnosis: pytest tests/unit/test_builder.py tests/unit/test_my_file.py::TestMyClass -q — if it fails, test_builder.py is contaminating.
Fix: Use _import_X_fresh() to reload the module with clean stubs before every test class.

Patching Gio.resources_lookup_data after real Gio is loaded#

patch("bootc_installer.defaults.image.Gio.resources_lookup_data", return_value=x) silently fails when the real Gio C-extension is already loaded. The patch target is the C method object, not a Python-wrappable attribute.

Fix: Reload with _import_image_fresh(), then set directly:

fresh = _import_image_fresh()
fresh.Gio.resources_lookup_data = MagicMock(return_value=x)

See tests/unit/test_image_helpers.py::TestLoadManifestOverrides for the canonical pattern.

Dialog stub staleness#

Each _build_gi_stubs() call creates a new BootcDialog = MagicMock() stored in sys.modules["bootc_installer.windows.dialog"]. Code that already ran from bootc_installer.windows.dialog import BootcDialog holds the old object. Asserting on the new stub: sys.modules["bootc_installer.windows.dialog"].BootcDialog.assert_called_once() will fail — it was never called.

Fix: Always assert on the module's own attribute:

assert _yn_mod.BootcDialog.call_count == 1 # not sys.modules[...].BootcDialog

See tests/unit/test_layouts.py for the canonical pattern.


Ruff / Python Quality#

Intentional out-of-order imports (GTK)#

GTK apps must call gi.require_version() before importing widgets. These imports always appear after the version pin and get # noqa: E402:

gi.require_version("Gtk", "4.0")
from gi.repository import Gtk # noqa: E402

Do NOT restructure these — they are intentional.

Common F821 patterns to watch#

  • encryption.py: _() used for i18n without from gettext import gettext as _
  • done.py: logger.debug() called with import logging present but no logger = logging.getLogger(...) — silent at import time, crashes at runtime

Check before committing#

python3 -m ruff check bootc_installer/ tests/

The codebase is ruff-clean. All new code must pass.


Coverage Gate#

Never raise above measured#

pytest tests/unit/ -q --cov=bootc_installer --cov-report=term-missing 2>&1 | tail -5

Use the integer floor (47 for 47.57%). pytest-cov displays rounded values — 47.57% shows as 48% in terminal output but the gate uses the raw decimal. Set --cov-fail-under=47 to be unambiguous.

When two PRs both change the gate#

Keep the higher value. The gate is a ratchet — never lower it. Resolve the conflict by taking max(a, b).


CI#

Missing CI checks on a PR#

GitHub Actions silently skips pull_request events when a PR branch has merge conflicts. If CI shows "no checks reported":

gh pr view N --json mergeable # look for "CONFLICTING"
git rebase origin/dev && git push --force-with-lease

Overlapping test PRs#

When multiple PRs add to the same test files (test_branding_parity.py, test_done.py, test_slurp_helpers.py):

  1. Rebase each branch onto latest dev after every merge
  2. Run pytest tests/unit/ -q after every conflict resolution before pushing
  3. "Keep both sides" of an additive test conflict can silently introduce indentation errors

Flatpak Manifests#

git sources fail in Flatpak sandbox#

"type": "git" sources fail with safe.bareRepository=explicit. Always use:

{"type": "archive", "url": "...", "sha256": "..."}

New .py files must be in meson.build#

Every new Python file must appear in sources = [...] in its subpackage's meson.build. The tests/unit/test_meson_sources.py test catches this. Fix the meson.build, not the test.


fisherman / Install Pipeline#

Windows data slurp timing#

The slurp scan must happen BEFORE partitioning — the source disk is often the target disk.
RAM scratch: /run/fisherman-slurp/ (Statfs("/run") minus 2GB reserve).

Offline install detection#

Check local_imgref in recipe OR live ISO indicators (/run/initramfs/live, /run/ostree-booted). processor.py passes additionalImageStores to fisherman recipe for ISO-baked OCI stores.

NTFS mounting#

Try kernel ntfs3 (faster, in-kernel since Linux 5.15) then fall back to ntfs-3g FUSE.


GStreamer / Video Playback#

Defer set_muted() and play() to the widget's map signal. Calling them before GstPlayer is constructed triggers GStreamer-Player-CRITICAL. Pattern:

self.connect("map", self.__on_map)

def __on_map(self, _widget):
    media_stream = self.video.get_media_stream()
    if media_stream and media_stream.is_prepared():
        media_stream.set_muted(True)
        media_stream.play()
    else:
        media_stream.connect("notify::prepared", self.__on_prepared)

Recipe / Image Catalog Override Chain#

RecipeLoader (utils/recipe.py) applies overrides in this priority order:

  1. /etc/bootc-installer/recipe.json (ISO/system override)
  2. $XDG_CONFIG_HOME/bootc-installer/recipe.json (user override)
  3. Bundled GResource version

Same for images.json. The ISO uses /etc/bootc-installer/images.json to replace the full multi-distro catalog with a single Dakota entry.


QR Phone Companion#

CompanionServer in utils/phone_companion.py runs openssl subprocess and opens a UDP socket to 8.8.8.8. Both block in CI. Any UI test that navigates past the QR wizard step must mock:

patch("bootc_installer.defaults.qr_companion.CompanionServer")
patch("bootc_installer.defaults.qr_companion.get_local_ip", return_value="127.0.0.1")

GLOBAL_CONFIG = None inside a method creates a local variable, not a module-level reset. Always add global GLOBAL_CONFIG before the assignment.


conn_check.py — Don't Check github.com for Connectivity#

Pattern to avoid:

urllib.request.urlopen("https://github.com", timeout=5) # WRONG

github.com is blocked in corporate environments and some geographic regions. The installer's actual dependency is ghcr.io (OCI registry). Use socket-level checks:

import socket
for host, port in [("ghcr.io", 443), ("8.8.8.8", 53)]:
    try:
        s = socket.create_connection((host, port), timeout=5)
        s.close()
        return True # connected
    except OSError:
        continue
return False # all failed

This probes the real OCI registry first (ghcr.io:443), then falls back to DNS (8.8.8.8:53) as a basic internet check.


fisherman checkRequiredTools — Always Include Late-Stage Tools#

Rule: If a tool is required at any step of the install pipeline, it must be in checkRequiredTools, even if it's only used in the very last step.

Why: fisherman fails silently late — the disk is already wiped and the OS is already installed by the time a missing tool is discovered. The only safe pattern is checking ALL required tools before touching any disk.

Known gap (now fixed): systemd-cryptenroll for TPM2 encryption types was missing. The install would succeed through 8 steps, then fail at TPM2 enrollment (step 9), leaving the disk wiped with no bootable system.

// checkRequiredTools checklist:
// - All partition tools (sfdisk, mkfs.*)
// - Encryption tools (cryptsetup + systemd-cryptenroll for TPM2)
// - Image tools (skopeo, podman)
// - Any tool called in post-install steps (systemd-cryptenroll, etc.)

Loop Devices in Kubernetes Containers#

Loop partition nodes (/dev/loopXpY) do NOT appear in Kubernetes privileged containers after sfdisk repartitions a loop device. The BLKRRPART ioctl that sfdisk uses to notify the kernel about partition table changes fails in containers.

fisherman's loopRescan() (detach + re-attach with --partscan) mitigates this for real hardware/VMs, but does NOT work reliably inside k8s pods.

Impact on testing: Automated integration tests using losetup + fisherman in Argo pods will fail at mkfs.fat /dev/loop0p1: No such file or directory.

Workaround for tests: Use a KubeVirt VM for full install testing. The validate step (fisherman validate recipe.json) uses os.Stat(disk) only and DOES work in containers (13/13 test cases pass).

Real-world impact: NONE. fisherman is intended for live ISO installs (bare metal, VMs). Loop device rescanning works correctly on real hardware.


Python Escape Sequences in GTK String Literals#

Strings used in GTK markup or display names must use raw strings if they contain backslash sequences that aren't valid Python escapes:

# WRONG — \| is not a valid Python escape; SyntaxWarning in 3.12, SyntaxError in 3.14+
"Czech (with <\|> key)"

# CORRECT — raw string, backslash is literal
r"Czech (with <\|> key)"

This affects any string with \|, \%, \- or other non-escape backslash combinations.


flatpak-builder --run: /app/bin Not in PATH#

When running the app via flatpak run org.flatpak.Builder --run _build manifest.json COMMAND, the default PATH inside the sandbox is:

/app/go/bin:/usr/bin:/bin

/app/bin is not included. Invoking bootc-installer directly fails with No such file or directory.

Fix: Always use the full path:

# Wrong
flatpak run org.flatpak.Builder --run _build manifest.json bootc-installer

# Correct
flatpak run org.flatpak.Builder --run _build manifest.json \
    sh -c 'BOOTC_DEMO=1 /app/bin/bootc-installer'

# Or set PATH explicitly
flatpak run org.flatpak.Builder --run _build manifest.json \
    sh -c 'PATH=/app/bin:$PATH BOOTC_DEMO=1 bootc-installer'

See dev.sh for the canonical form.


flatpak-builder --run: Debug Log Goes to XDG App Cache#

When running via flatpak-builder --run (not a full install), the app writes its debug log to the Flatpak XDG cache path, not ~/.cache/bootc-installer/:

# flatpak-builder --run (dev loop)
~/.var/app/org.bootcinstaller.Installer.Devel/cache/bootc-installer/installer-debug.log

# Full flatpak install
~/.cache/bootc-installer/installer-debug.log (via XDG_CACHE_HOME redirect)

./dev.sh --logs tails the correct path automatically.


DeploymentDirFn mocking masks real command failures#

DefaultDeploymentDir calls ostree admin --print-current-dir to locate the
deployment directory on the installed target. Every test that exercises
WriteHostname (ostree path) replaces DeploymentDirFn with a stub that
returns a fake path — meaning DefaultDeploymentDir itself is never called
in any test.

The real command always exits 1 against a freshly-installed target (never booted,
no booted-deployment state in the kernel). This caused a fatal installer crash
on every real install for weeks while CI passed.

The CI e2e wrapper (scripts/fisherman-install.sh in dakota-iso) silently
caught the crash and patched the hostname manually. It treated the symptom,
not the cause, and masked the failure from every CI run.

Fix: DefaultDeploymentDir now falls back to filepath.Glob over
ostree/deploy/*/deploy/* when --print-current-dir fails. Three regression
tests cover the fallback, happy path, and empty-sysroot error — and they call
DefaultDeploymentDir directly through post.Exec, not via the stub.

Rule: When a function is injected via a package-level var Fn = Default...
pattern, the default implementation must have at least one test that exercises
it end-to-end. Stub-only coverage is no coverage.


fisherman-install.sh wrapper: symptom workaround, not a fix#

The scripts/fisherman-install.sh wrapper in dakota-iso was written to patch
around the hostname-write crash at the CI level. It detects the specific
"ostree admin --print-current-dir" error in the log, re-mounts the installed
disk, and writes /etc/hostname directly.

This pattern is dangerous: it lets broken releases ship because CI appears green.
If you see a wrapper script that catches a specific fatal error and patches
around it, treat it as a bug report in disguise — find and fix the root
cause in fisherman, then remove the workaround.

The wrapper is still present in scripts/fisherman-install.sh as a safety net
but is no longer load-bearing now that DefaultDeploymentDir has the glob fallback.


Branch Protection: Rulesets vs Classic Protection#

This repo uses GitHub repository rulesets (not classic branch protection). The REST API endpoint is different:

# List rulesets
gh api repos/projectbluefin/bootc-installer/rulesets

# Delete a ruleset (removes all its rules including required status checks)
gh api --method DELETE repos/projectbluefin/bootc-installer/rulesets/<id>

# Classic branch protection (does NOT apply here — returns 404)
gh api repos/projectbluefin/bootc-installer/branches/dev/protection

If direct pushes to dev are blocked with "2 of 2 required status checks expected", the block comes from a ruleset, not classic protection. Delete the ruleset to allow direct pushes.


Changing default filesystem requires live-env tool check (2026-06-15)#

Symptom: fisherman: fatal: missing required host tool: "mkfs.xfs" not found in PATH
immediately after clicking Install. Affects every user on the new ISO.

Cause: When the installer default changed from btrfs to xfs, fisherman's preflight
check for mkfs.xfs became active. The live ISO environment (GnomeOS/freedesktop-sdk base)
did not have xfsprogs installed — only btrfs-progs was present.

Fix in dakota-iso: Copy mkfs.xfs from the Debian build stage into the final live image:

COPY --from=initramfs-builder /usr/sbin/mkfs.xfs /usr/sbin/mkfs.xfs

Rule: Any change to the default filesystem (in images.json, recipe.json, or
defaults/disk.py) MUST be followed by a full E2E install test in the target live
environment. Unit tests mock fisherman — they cannot catch missing host tools.
The check lives in fisherman/cmd/fisherman/main.go (the checkRequiredTools slice).
Before changing a default, verify every tool in that slice is present in the live squashfs.

How to check: podman unshare bash -c "M=\$(podman image mount <installer-image>); ls \$M/usr/sbin/mkfs.xfs || echo MISSING"

See: https://github.com/ublue-os/bluefin/discussions/4754


The fisherman submodule tracked the wrong branch (2026-08-01)#

.gitmodules declared branch = dev, but fisherman's active line is main — on
2026-08-01 main was 25 commits ahead of dev. fisherman's default branch is dev,
so a PR opened there with the default base lands on the branch nobody ships, and
git submodule update --remote pulled from a stale line.

The pointer had not moved since 2026-06-23. Everything that shipped in between —
the flatpak in every stable dakota ISO — was built from that June commit. A user hit an
ENOSPC install failure whose fix had been merged to fisherman main and still could not
reach them, because this pointer is the only bridge.

Rules:

  • fisherman PRs target main. .gitmodules now tracks main.
  • Bumping this pointer is what ships a fisherman fix. Merging in fisherman is not shipping.
  • Check the gap before assuming a fix is live:
gh api repos/projectbluefin/bootc-installer/contents/fisherman -q .sha
gh api repos/projectbluefin/fisherman/compare/<that-sha>...main -q '{ahead:.ahead_by,behind:.behind_by}'

Delivery chain — three hops, each independently stale-able:

fisherman main → bootc-installer submodule → flatpak GitHub release → dakota ISO

The ISO downloads the bundle from a release asset, not from the branch:
releases/latest/download/org.bootcinstaller.Installer.flatpak for the stable channel,
releases/download/latest-dev/...Devel.flatpak for dev. So a merge to prod alone does
not reach a stable ISO — a v* release must be cut.


Deleting a release tag is a one-way door (2026-08-01)#

Both flatpak workflows published the rolling dev bundle by deleting the
latest-dev release and tag and then re-creating them on every push to dev.

Once the immutable-release ruleset took effect, that pattern became a self-destruct:
a tag that has ever carried a release is permanently banned from re-creation. The
first dev push after the ruleset landed deleted the release and could not put it
back — gh release create latest-dev fails with

HTTP 422: Validation Failed
pre_receive Repository rule violations found
Cannot create ref due to creations being restricted.

for CI's token and for a maintainer PAT. Re-running the job does not help. The whole
dev flatpak channel went down: dakota-iso's install-flatpaks.sh 404s on
releases/download/latest-dev/... and silently falls back to the upstream tuna-os
bundle, so a live ISO quietly ships someone else's installer.

The ban is per tag name, not global — arbitrary new tags create fine. latest-dev
itself is unusable forever.

Rules:

  • Never gh release delete --cleanup-tag a rolling channel tag. Create-if-missing,
    then gh release upload --clobber. Both workflows now do this.
  • The dev channel tag is now dev-rolling. dakota-iso fetches
    releases/download/dev-rolling/org.bootcinstaller.Installer.Devel.flatpak; the two
    repos must be changed together.
  • The workflow comment already warned about this for latest-stable. It was right.
Documents
Changelogs
Bluefin LTS Errata
Pin Log
2024-12-30-ublue-2024-wrapup
2025-01-01-announcements-archive
2025-02-23-february-update
2025-05-14-bluefin-f42
2025-06-23-bazaar-default
2025-07-06-fresh-bluefin-isos-and-bazaar
2025-07-11-four-years-of-ublue
2025-07-15-bold-brew
2025-07-17-ask-projectbluefin
2025-08-01-august-wallpapers
2025-08-08-bluefin-on-lfx
2025-08-29-github-oss-fund
2025-09-17-color-with-bluefin
2025-09-18-bluefin-lts-and-gdx
2025-09-23-LTS-at-indiafoss
2025-10-28-bluefin-autumn
2025-10-31-fastfetch-metrics
2025-11-15-cloud-native-milestone-15-million
2025-11-16-coreos-desktop
2025-11-24-new-just-and-bbrew
2025-11-27-bluefin-and-paleoartists
2025-12-04-flatpak-support-in-brewfiles
2025-12-06-interview-with-michael-tunnell
2025-12-07-documentation-updates
2025-12-14-huntress-holiday-wallpapers
2025-12-15-easier-homebrew-installation-for-custom-images
2025-12-27-upcoming-homebrew-cli-changes
2025-12-30-bluefin-2025-wrapup
2026-01-03-modernizing-custom-images
2026-02-01-automated-reports-changelogs
2026-03-13-bluefin-cli-mac-wsl
2026-03-27-bluefin-lts-gnome-49-50
2026-03-29-composefs-fisherman
2026-03-29-composefs-fisherman-design
2026-03-30-boot-verification
2026-03-30-boot-verification-design
2026-03-30-proportional-progress-tracking
2026-03-30-proportional-progress-tracking-design
2026-04-02-state-of-ecosystem
2026-04-19-dakota-alpha-1
2026-05-12-bluefin-spring-2026
2026-05-13-bluefin-spring-2026-2
2026-05-14-making-our-own-fate
2026-05-15-hummingbird
2026-05-23-gradia-capture-bluefin
2026-05-28-knuckle
2026-06-11-promotion-pr-body
AGENTS
AGENTS
AGENTS
AGENTS
AGENTS
Building a Custom Bluefin Image
CI_CD_GUIDE
CLAUDE
CLAUDE
CONTRIBUTING
CONTRIBUTING
CONTRIBUTING
CONTRIBUTING
How can I install Double Commander on Bluefin (an immutable Linux OS), coming from Arch Linux?
How can you fix random GPU artifacts and hard freezes on an AMD Framework 16 laptop running Linux (Bluefin/Fedora)?
How do I install the Cloudflare WARP (One) client on Bluefin?
How to Reset a User's Home Directory to Defaults on Bluefin
INDEX
MAINTAINERS
MULTI_VARIANT_BUILD
PITFALLS
PULL_REQUEST_TEMPLATE
Plex Media Server
README
README
README
README
README
README
README
README
SECURITY
SECURITY
SKILL
SKILL
SKILL
SKILL
TRANSLATING
Update Process
Which Bluefin ISO is recommended for a Lenovo Yoga Pro 9i with an NVIDIA RTX 4050 for Python data science and Machine Learning with CUDA?
action-reference
actionadon
add-package
administration
agentic-contributing
ai
analytics
architect
architecture
artwork
blog-poster.agent
bluefin-dx
bonedigger-overview
bonedigger-templates
bonedigger-ujust
bst-overrides
build
build
buildstream
ci
ci
ci
code-of-conduct
command-line
composite-actions
consumer-guide
consumer-validation
contributing
conventional-commit.prompt
copilot-instructions
copilot-instructions
copilot-instructions
copilot-instructions
dakota-tpm2-validation
debugging
demo-mode-e2e
determinism
dinosaurs
downloads
downloads-testing
driver-versions
e2e-ci
e2e-feature-verification
encryption-matrix
factory-operations
failure-paths
feedback-loop
gstreamer-codec-validation
human-gates
images
index
index
installation
installer
label-workflow
libpastry-integration
live-iso
local-ota
luks-testing
merge-queue
mission
multi-arch
music
not-bluefin
oci-assembly
oci-layers
onboarding
overview
packaging-binaries
packaging-gnome-extensions
packaging-go
packaging-rust
packaging-zig
patch-junctions
patches
pr-checklist
pr-review
press-kit
projects
pull_request_template
pull_request_template
pull_request_template
qr-phone-companion
quickstart
r2-promotion
release-qualification
remove-package
reports
reusable-workflow
skill-improvement
supply-chain
t2-mac
testing
troubleshooting
ujust-recipes
update-refs
upgrade-and-migration
ux-ubuntu-provision
values
variants
vm-stack
workflow