debian-atomic/docs/bootc-install-issue-report.md

bootc install Issue: Technical Analysis Report

Document Version: 1.0
Date: August 17, 2024
Status: Investigation In Progress
Issue Type: bootc install "No commit objects found" Error

Executive Summary

This report documents a persistent issue with bootc install functionality where the command consistently fails with "No commit objects found" error, despite having properly structured container images with valid OSTree repositories and commits. The issue affects both custom-built images and official Fedora bootc images, suggesting a fundamental architectural or configuration problem rather than an image-specific issue.

Problem Description

Error Message

error: Installing to filesystem: Creating source info from a given imageref: Subprocess failed: ExitStatus(unix_wait_status(256))
error: No commit objects found

When It Occurs

• Command: bootc install to-existing-root --source-imgref oci:<image-reference>
• Environment: VM with container runtime (podman) and bootc installed
• Images Tested: Custom-built bootc-compatible images and official Fedora bootc images
• Result: Consistent failure across all tested images

Technical Investigation

1. Image Structure Analysis

Custom-Built Image Structure

/sysroot/ostree/repo/
├── config (mode=bare)
├── objects/ (256 directories: 00-ff, containing actual OSTree objects)
│   ├── 00/ (contains .commit, .meta, .dirtree files)
│   ├── 01/ (contains .commit, .meta, .dirtree files)
│   └── ... (continues through ff)
├── refs/
│   └── heads/
│       └── custom-atomic/base (reference to commit hash)
├── state/
└── tmp/

Official Fedora bootc Image Structure

/sysroot/ostree/repo/
├── config (mode=bare-split-xattrs)
├── objects/ (256 directories: 00-ff, containing actual OSTree objects)
│   ├── 00/ (contains .commit, .meta, .dirtree files)
│   ├── 01/ (contains .commit, .meta, .dirtree files)
│   └── ... (continues through ff)
├── refs/
│   └── heads/ (empty - no references)
├── state/
└── tmp/

2. OSTree Repository Validation

Custom Image OSTree Status

# Repository references
$ ostree --repo=/sysroot/ostree/repo refs
custom-atomic/base

# Commit details
$ ostree --repo=/sysroot/ostree/repo log custom-atomic/base
commit 31ffa392d54da035a2ea2008c7a7f1c4255a5a07d83ec1109a403a12376c4a54
ContentChecksum: f44c4a29c409ee11392de50c46f9863f4d9d7f4922bebb1010c7a191c1774eb0
Date: 2025-08-17 20:26:07 +0000
    Custom bootc Base Image

Fedora Image OSTree Status

# Repository references
$ ostree --repo=/sysroot/ostree/repo refs
# No output - empty references

# Cannot check commit details without references

3. Container Runtime Configuration

Storage Configuration

# /etc/containers/storage.conf
[storage.pull_options]
enable_partial_images = "false"

Note: This setting was specifically configured to address a known issue with bootc and partial image pulls, as documented in Fedora bootc troubleshooting guides.

Container Runtime Status

• Podman Version: 5.4.2+ds1-2+b1
• Storage Driver: overlay (auto-detected)
• Image Pull: Full images (partial images disabled)

4. bootc Environment Analysis

bootc Installation

• Version: 1.6.0
• Installation Method: Package installation (not from source)
• Dependencies: All required packages present
• System Integration: Properly integrated with systemd

System Environment

• OS: Linux-based distribution
• Architecture: x86_64
• Container Runtime: Podman with full container support
• Network: Internet access for image pulling

Root Cause Analysis

Hypothesis 1: OSTree Reference Structure Mismatch

Status: ❌ Ruled Out

Reasoning:

• Custom image has proper OSTree references
• Fedora image has no references but should work
• Both images contain valid OSTree objects
• Reference structure is not the determining factor

Hypothesis 2: Container Image Format Issues

Status: ❌ Ruled Out

Reasoning:

• Images are properly formatted OCI containers
• Images can be pulled and run successfully
• OSTree objects are accessible within running containers
• Image format is not the issue

Hypothesis 3: Host System Configuration

Status: ⚠️ Partially Addressed

Reasoning:

• enable_partial_images = false was configured
• Error persists despite configuration fix
• Configuration warnings still appear in logs
• May be additional configuration requirements

Hypothesis 4: bootc Architecture Evolution

Status: 🔍 Most Likely

Reasoning:

• Modern bootc may not rely on traditional OSTree references
• Official Fedora images also lack references
• bootc may expect different image structure or metadata
• Architecture may have shifted from OSTree-centric to container-native

Hypothesis 5: Missing bootc Components

Status: 🔍 Needs Investigation

Reasoning:

• bootc 1.6.0 is installed and functional
• May require additional system components
• Could be missing bootc-specific systemd services
• May need specific kernel or initramfs configuration

Technical Details Requiring Investigation

1. bootc Image Recognition

Question: How does bootc identify and validate bootable container images?

Current Understanding: bootc looks for OSTree repositories in /sysroot/ostree/repo/

Unknown:

• What specific metadata or structure bootc requires
• How bootc distinguishes bootable from non-bootable images
• Whether bootc uses OSTree references or different mechanisms

2. Container Image Metadata

Question: What OCI image metadata does bootc expect for bootable images?

Current Understanding: Images contain OSTree repositories

Unknown:

• Required OCI labels or annotations
• Expected image configuration
• Required manifest structure

3. System Integration Requirements

Question: What system-level components does bootc require for installation?

Current Understanding: bootc needs container runtime and basic system tools

Unknown:

• Required kernel modules or features
• Specific systemd services or units
• Hardware or firmware requirements

4. bootc Version Compatibility

Question: Are there version-specific requirements or breaking changes?

Current Understanding: Using bootc 1.6.0

Unknown:

• Version compatibility matrix
• Breaking changes in recent versions
• Required minimum versions for specific features

Testing Methodology

1. Image Validation Tests

• ✅ OSTree Repository Structure: Validated
• ✅ OSTree Objects: Present and accessible
• ✅ OSTree References: Created and accessible
• ✅ Container Runtime: Functional
• ❌ bootc install: Fails consistently

2. Environment Validation Tests

• ✅ bootc CLI: Functional
• ✅ Container Pull: Successful
• ✅ OSTree Commands: Functional
• ✅ System Integration: Proper
• ❌ bootc install: Fails consistently

3. Cross-Image Validation

• ✅ Custom Image: Properly structured, fails bootc install
• ✅ Fedora Image: Official image, fails bootc install
• ❌ Common Factor: bootc install failure

Potential Solutions

1. bootc Configuration Investigation

Approach: Research bootc configuration requirements and options

Actions:

• Investigate bootc configuration files
• Check for required environment variables
• Research bootc-specific system requirements

2. Image Metadata Enhancement

Approach: Add required OCI metadata to images

Actions:

• Research required OCI labels
• Add bootc-specific annotations
• Verify manifest structure

3. System Component Verification

Approach: Ensure all required system components are present

Actions:

• Verify kernel requirements
• Check systemd service requirements
• Validate hardware/firmware support

4. bootc Version Analysis

Approach: Investigate version-specific requirements

Actions:

• Research bootc version compatibility
• Check for breaking changes
• Verify minimum version requirements

Next Steps

Immediate Actions

1. Research bootc 1.6.0 documentation for installation requirements
2. Investigate bootc configuration options and required settings
3. Research OCI image requirements for bootable images
4. Check system integration requirements for bootc install

Medium-term Actions

1. Test with different bootc versions to identify version-specific issues
2. Research bootc architecture changes in recent versions
3. Investigate alternative bootc installation methods
4. Research bootc debugging and logging options

Long-term Actions

1. Document bootc requirements for different environments
2. Create bootc compatibility matrix for various configurations
3. Develop bootc testing methodology for validation
4. Research bootc best practices for different use cases

Conclusion

The "No commit objects found" error with bootc install represents a complex technical issue that cannot be resolved through traditional OSTree repository fixes. The fact that both custom-built and official Fedora bootc images fail with the same error suggests a fundamental architectural or configuration requirement that is not currently understood.

The investigation has ruled out common causes like OSTree structure, image format, and basic configuration issues. The problem likely lies in modern bootc's evolved architecture, which may have moved away from traditional OSTree-centric approaches to a more container-native paradigm.

Further research is needed to understand:

1. Modern bootc architecture and its requirements
2. OCI image metadata requirements for bootable images
3. System integration requirements for bootc install
4. Version compatibility and breaking changes

This issue represents a significant gap in understanding of modern bootc functionality and requires deeper investigation into the tool's current architecture and requirements.

References

1. bootc Documentation: Official bootc project documentation
2. Fedora bootc Guides: Fedora-specific bootc implementation guides
3. OSTree Documentation: OSTree repository structure and management
4. OCI Specification: Open Container Initiative image format requirements
5. Container Runtime Documentation: Podman and container runtime requirements

---

Document Status: Investigation In Progress
Next Review: After Gemini research results
Author: Technical Investigation Team
Reviewer: Development Team