Repository navigation
Troubleshooting
Start with bd-archive --version and the relevant command's --help. Keep the
full diagnostic output and command when reporting a problem, omitting private
paths if necessary.
After a uv tool install, run uv tool update-shell and restart the shell if
bd-archive is not on PATH. The Python environment does not contain the external
system tools; install the missing executable's package. See Installation
for the per-command table and the par2/dvd+rw-mediainfo exceptions.
Use an existing optical block device, such as -D /dev/sr0. verify takes the
device as a positional target instead. If several drives exist, choose the one
holding the disc. For creation without media or a drive, specify -b BYTES.
An unreadable/blank disc cannot be verified as an archive.
Raw create plans the source across discs and builds one disc per run, so a
large source simply needs several runs. Each unit must fit on a disc together
with attachments, metadata and the -r recovery data (5% by default).
If one does not, choose finer --group-by grouping, a smaller -r, larger
media, or use -m dar to split the archive into slices. -r 0 deliberately
removes repair capability; it does not remove checksums.
A very large file count can hit the automatic PAR2 planner's 32,768 non-empty-file limit. A DAR archive reduces those files to slices for recovery purposes.
Use separate, non-overlapping source, output and workdir trees. Keep the
selected files unchanged until creation finishes; a change detected while
hashing, generating recovery or measuring the disc stops creation and removes
its output. Unsupported links, special files and line-break filenames are
rejected. Metadata-like names are allowed inside the source, but an attachment's
name cannot collide with -n or the disc-root metadata.
If burn reports a changed disc folder after you kept the source, a hardlinked
source file was probably edited; create the disc again. When removing archived
units, create refuses and removes nothing if a selected unit changed after the
scan. See Raw data discs.
Creation stops when multiple selected regular-file names refer to the same inode on the same filesystem. The error lists conflicting relative paths. This applies to raw and DAR creation, with either folder or ISO output. External hardlinks do not count, and neither do paths explicitly deferred by DAR auto-deferral.
Select a source containing only one of the linked names, or explicitly prepare independent copies if duplicate content on disc is intentional. Reflink copies are independent files and remain allowed. The program does not alter your source or silently convert hardlinks.
Creation refuses an output with a non-empty discs/, an existing raw disc/
or manifest.json, or existing images/disc_*.iso. Use a fresh output so old
and new sets cannot be mixed. Creation has no resume option. Folder output
without a valid manifest (manifest.json for a raw disc, discs/manifest.json
for a DAR set) is incomplete and cannot be burned automatically.
Keep the complete output together, preserving file names, permissions and mtimes
when copying it. burn rejects added, removed, resized or retimestamped files,
as well as links and special entries. Recreate changed sets in a fresh output.
These metadata checks do not detect every form of corruption; use verify
for integrity checks. Keep prepared files unchanged throughout burning.
For multi-image sets, burn compares media capacity with the largest image and
rejects more than 5% excess. Use the intended media class. --skip-fit-check
overrides this but also disables the too-small check. Single-image sets permit
unused space. See Burning.
Close applications using the drive, such as ripping or burning programs. The
burn command offers a retry; optional lsof can identify holders of the optical
or associated SCSI device. The program does not close other applications for you.
Typical growisofs output before the failure: the written byte count stops
changing for several seconds while the status shows @0.0x, RBU 0.0% and
UBU 0.0%, then:
:-[ WRITE@LBA=...h failed with SK=5h/INVALID ADDRESS FOR WRITE]: Invalid argument
:-( write failed: Invalid argument
The source stopped delivering data (RBU 0.0%), the drive's buffer ran empty
(UBU 0.0%), and after the stall the drive no longer accepted the write
position. growisofs waits for data without limit; the refusal comes from the
drive. The session is closed at that point and the disc is unusable: burn the
image again on fresh media with --start N.
Fix the source, not the drive: raise the ring buffer, for example
--buffer 1G, when the source is a NAS, a hard disk busy with other work or
another slow or unreliable storage; copy the prepared folders or images to
local, idle storage before burning; keep the source free of other heavy I/O
during the burn. A lower speed (-S) stretches the buffer but does not bridge
a pause longer than the buffer lasts. See Burning.
If growisofs instead stops at startup with unable to anonymously mmap, the
buffer could not be allocated: lower --buffer, or raise the locked-memory
hard limit (ulimit -Hl) if it lies between 48 MiB and the buffer size on a
system where bd-archive cannot adjust it.
burn gives write commands at least 180 seconds by default. Use
--write-timeout 900 for a longer minimum. This does not extend the separate
mount, flush, calibration or close-session timeouts. A kernel write timeout can
still mean a stuck drive or connection fault; save growisofs output and kernel
messages rather than assuming that more waiting will always help.
If the helper is missing after updating an editable checkout, install the native build requirements and rebuild from the checkout:
uv tool install --force --editable .Wrong-architecture or incompatible-libc libraries must be rebuilt for the target
machine. The startup check also rejects static/non-ELF wrappers, setuid/setgid
or file-capability growisofs binaries, and pre-existing LD_PRELOAD or LD_AUDIT
overrides. Resolve the reported installation or launch configuration; the tool
never silently burns without its timeout helper. It makes no automatic changes
to system permissions or global settings. See Installation.
After burning, eject/reload lets the kernel recognize the changed medium. Push a slim-drive tray in manually. Once loaded, the tool retries mounting before offering another prompt. The burned disc is also detected in another drive; see Verify in another drive.
ISO operations need udisks2, D-Bus and the required Polkit permission. Physical
mounts first try mount, then udisksctl if available. Headless sessions and
containers may not have a usable service or policy. Check the reported mount
error; see Docker for container limits.
Read the message: 1 can mean PAR2-repairable damage or an operational failure such as a missing dependency or failed mount. Standalone verification does not repair anything. A new burn must be OK; repairable damage does not pass the post-burn check. See Verification.
Use an empty directory, or a previous restore of the same chain identified by
.bd-archive-extract. Restore overwrites existing files. Do not add a marker to
bypass this check for unrelated data. The chain name must match the supplied
archive. Use a fresh directory to restore a different chain or historical state.
It is collecting an open-ended set. Insert another disc, or press e while waiting to begin extracting the collected generations. The initial disc and repair reinsertions use explicit prompts. See Restoring.
All collected slices remain in staging until restoration finishes. Move the workflow to a sufficiently large dedicated workdir and rerun; the program does not fall back automatically from an explicit tmpfs path. Budget restored output space as well. See Storage and layout.
A later clean extraction does not remove an earlier corrupted-files.txt.
Existing staged slices are also reused, so replacing an ISO does not itself
force a fresh copy. Compare the current run's diagnostics with the report's
timestamp. A fresh output/workdir provides an independent retry without reusing
old slices or reports.
--base must point to an existing catalog slice with the same name as -n.
--pack-with must contain DAR data, leave room for a first slice, and not already
contain this new name/generation. A changed chain name is a different archive;
renaming files is not a substitute for an incremental. See
Incrementals and packing.
Getting started
Create archives
Use your archives
Reference