Skip to content

Troubleshooting and FAQ

Answers to the questions and warnings that come up most often. For the concepts behind these, see the safety model and the timezone model.

Warnings

"camera clock implies UTC-5 but config says UTC-4"

This is the timezone cross-check firing. A DJI camera's filename embeds local time while its metadata is UTC, so media-ingest can recover the offset the camera's clock was actually set to. That inferred offset does not match the trip timezone in ingest.toml.

Two things could be true:

  • The trip timezone is wrong. If the whole trip should be UTC-5 and you configured UTC-4, fix timezone in ingest.toml and re-run plan.
  • That one camera's clock was off. DJI clocks drift and are not always reset per trip. Confirm by running align on one of that camera's clips and comparing against a neighboring iPhone photo, whose clock is trusted. If the camera really was off, the trip timezone is still correct and the names will be right; the warning is just telling you the camera disagreed.

The warning never blocks apply. It is a prompt to check.

"capture date ... outside trip range"

A file's corrected capture date falls outside the start/end range you set at init. Common causes are a test clip shot before you left, a camera with a badly wrong clock, or a trip range that is simply too narrow. The file is still planned and will still be renamed; widen the range in ingest.toml if the date is legitimate, or investigate the file if it is not.

"could not identify device; left in place"

media-ingest did not recognize the device or file type, so it will not guess a name or a time for it. See "unknown devices" below.

"no usable capture timestamp; left in place"

The file was recognized, but none of its timestamp fields could be read, so there is no reliable time to build a name from. It is left where it is.

Excluded files

plan excludes files it cannot confidently place and lists them, with a reason, in both the summary and the timeline report. Nothing excluded is moved or altered; it stays exactly where it is. The reasons are:

  • Empty or aborted recording (under 4 KB). Usually a stub file left behind by a failed take.
  • Duplicate content. Two files hash identically, so only the first (by path order) is planned. media-ingest confirms duplicates with a full-file hash before excluding either, so near-identical but distinct clips are never wrongly dropped.
  • Unrecognized device or type. See below.
  • No usable timestamp. See above.

If you want an excluded file organized anyway, you can rename it by hand; media-ingest simply declines to guess.

Unknown devices

If scan reports files as unknown, media-ingest could not match them to a known device profile. It supports DJI Osmo Pocket 3 and Action 6, DJI Mic 3, DJI Osmo audio sidecars, iPhone photos and video, generic EXIF cameras, and GoPro HERO 10 through 19. Files from anything else, or files stripped of their metadata, come back unknown and are left in place.

If the unknown files are from a device you expect to be supported, check that their metadata is intact (a re-export or a cloud round-trip can strip EXIF and QuickTime tags) and that exiftool can read them. Supporting a genuinely new device requires a new profile in the tool's detection logic.

Re-running after an interruption

If apply stops partway through, from a full disk, an unplugged drive, or a Ctrl-C, do not undo. Just run media-ingest apply again. apply is idempotent: files already at their destination are recognized (source gone, destination present with the matching hash) and counted as "already done", so a second run only finishes the remaining moves. See idempotent apply versus undo.

Undo is for changing your mind about a completed apply, not for recovering from an interruption.

"content changed since scan"

apply re-hashes each file immediately before moving it and aborts that move if the content no longer matches what scan recorded. If you see this, a file changed between scanning and applying (edited, re-exported, or replaced). Re-run scan and plan to pick up the current state, then apply again.

"No ingest.toml found"

Every command except init needs a project config. media-ingest looks for ingest.toml in the current directory and walks up through parents to find it, so you can run from anywhere inside the project. If it still cannot find one, you are outside the project tree, or you have not run media-ingest init yet. Run init at the project root first, or pass --root to point at the project.

Where is everything stored

Everything media-ingest produces lives in .ingest/ at the project root:

  • manifest.json from scan,
  • plan.json and report.html from plan,
  • apply-log.jsonl, the journal apply writes and undo reads.

Deleting .ingest/ resets you to before scan. It does not touch your media.