Troubleshooting¶
The command did not change anything¶
Dry run is the default. Review the report, then add --apply or set
ARCHIVIST_APPLY=true.
archivist --parent-folder "C:\photos" --apply
Image transfers additionally require an explicit yes in an interactive terminal.
Listing alone remains read-only even with --apply. No matching pictures is a
no-op. See Image workflows for action selection and approval rules.
An image workflow stopped partway through¶
New image workflows stop on incomplete discovery, changed inputs, unsafe or occupied targets, extraction/transfer errors and report failures. They do not roll back completed moves. Read completed/remaining counts and retained-copy messages before retrying. Previously extracted folders may remain; original ZIPs not yet removed are retained. Existing extraction folders are not merged in image mode, so resolve those outputs deliberately before a new attempt.
There is no overwrite switch for destination pictures. Source and destination must
be disjoint. Source read-only flags are not cleared for picture moves; --force
applies to ZIP disposal and legacy cleanup, and is rejected with --copy.
An archive was skipped¶
Common reasons include:
The destination folder already exists and the run is non-interactive.
The destination is a file, link, or Windows junction.
A file in the archive conflicts with an existing folder, or the reverse.
A replacement or archive is read-only and
--forceis not set.The archive needs more free space than is available after the 100 MB reserve.
The archive exceeds the ZIP-bomb expansion thresholds.
The report records the exact reason next to the skipped archive.
Read-only items remain¶
Archivist preserves read-only archives and cleanup targets by default. Pass --force to clear the
flag before removal.
archivist --parent-folder "C:\photos" --apply --force
Docker reports a permission error¶
The image runs as UID 65532. Ensure that UID can write to the mounted folder, or run the container
with your current Linux user.
chown -R 65532 /path/to/photos
# Or
docker run --rm --user $(id -u):$(id -g) -v "/path/to/photos:/data" archivist
Invalid environment configuration¶
Boolean variables accept true/false, 1/0, yes/no, and on/off. The maximum size must
be a whole number.
Exit codes¶
Code |
Meaning |
|---|---|
|
The run finished. Individual skipped items remain in the report. |
|
Invalid environment configuration, cancellation, or an incomplete/unapproved image workflow. |
|
Options, the parent folder, or the report destination are invalid. |
Still blocked¶
Include the command, platform, Archivist version, and relevant report lines when opening an issue. Remove personal paths or filenames before posting logs publicly.