Troubleshooting: Repository and Package Manager Issues

Troubleshooting: Repository and Package Manager Issues

When building a distribution, package managers are prone to database corruption, conflicting library versions, and hash mismatches.

Common Package Manager Failure Modes

1. Hash Sum Mismatches / Corrupted Metadata

Symptom:

E: Failed to fetch http://repo.byol.org/x86_64/curl-8.5.0.byol
   Hash Sum mismatch: Expected e3b0c442... but got a89f2100...

Cause: - The repository maintainer updated the binary package without re-running byol-index to regenerate index.json. - A proxy server or CDN cached an outdated version of index.json while serving a newly uploaded package payload. Remedy: - Always regenerate and sign metadata atomically after adding or modifying packages. - Ensure your HTTP server sets Cache-Control: no-cache, no-store, must-revalidate on repository metadata files (index.json), while allowing long cache TTLs on immutable binary package files (*.byol.tar.zst).

2. Dependency Deadlocks (Circular Conflicts)

Symptom:

Error: Transaction test error:
  package A-1.0 conflicts with B-1.0
  package B-1.0 requires A-1.0

Cause: Package \(A\) was compiled with an optional feature enabling \(B\), while \(B\) contains files that overlap with \(A\). Remedy: - Inspect package file listings using tar --zstd -tf <package> to identify overlapping files. - Introduce virtual subpackages (e.g., splitting libfoo runtime libraries from foo-bin command-line executables).

3. Missing Post-Install Scriptlet Execution

Symptom: A newly installed library (libcrypto.so.3) is present in /usr/lib, but newly launched applications cannot find it:

error while loading shared libraries: libcrypto.so.3: cannot open shared object file

Cause: The dynamic linker maintains an indexed binary cache in /etc/ld.so.cache. After installing shared libraries, /sbin/ldconfig must be executed to refresh the cache. Remedy: Package manager post-install hooks must automatically trigger triggers/hooks for: - ldconfig: Shared library cache. - update-desktop-database: Desktop menu entries. - gtk-update-icon-cache: GUI icon themes. - update-ca-certificates: SSL/TLS trust stores.