Files

An overview of file handling and file-version production in fylr, and a how-to for the /inspect/files page — its columns, filters, file states, and the actions you can run on files.

The /inspect/files page

Open <fylr url>/inspect/files. The page lists every file and its children. For each original file that has been uploaded — or linked via URL — children (versions) are calculated in the background. How many children are produced depends on the recipes triggered by the file's type and other file metadata. Each original and child file has a status that shows what the background workers have done, and surfaces any errors.

The list is paged. Click a row to open the single-file page, which shows every field of that file (preview, location, checksums, compile info, the linked object ids, and the full status message).

Columns

Column	Meaning
ID	The file's EAS id. The checkbox selects the file for an action.
Source ID	For a version, the id of the file it was produced from.
Location ID	The storage location holding the file (empty for remote-only files).
Remote URL	Checked when the file is linked by a remote URL rather than stored locally.
Leave On Remote	Checked when the file is intentionally kept on remote and not copied in.
Version	The version name (original, or a produced version such as a preview or thumbnail).
Filename / Size	The file name and size.
Status API	The coarse, API-facing status (pending, processing, sync, done, failed).
Status	The precise internal status (see File States).
Status Msg	The status / error message, truncated — hover, or open the file, to read it in full.
Original / Produce Versions / Autogenerated / Watermark	Flags: whether the file is an original, is set to produce versions, was auto-generated, or is watermarked.
Class / Extension	The file class (image, video, audio, …) and extension.
Info	Compile info.
Object Id(s)	The objects that link this file.

Filters

The two filter rows above the list narrow it down. Dropdowns are populated from the current data and show a [count] per option, so you can see at a glance how many files match. Set any combination and press Search.

Filter	What it does
Search	Free-text match on ID / Name / Reference / Extension / Status Message. Accepts id sets and ranges — e.g. id:<1,2,30-34> — and multiple terms separated by ;.
Version	Restrict to one version name (e.g. original or a specific produced version).
Class	Restrict to a file class; the option's tooltip lists the extensions in that class.
Extension	Restrict to a single file extension.
Size	Size bucket: 0 B, > 0 B, ≤ 100 KB, ≤ 1 MB, ≤ 10 MB, ≤ 100 MB, > 100 MB.
Location	Restrict by storage location — see File Locations.
Status	Restrict to one internal status.
Child Status	Restrict to files that have a child in the chosen status (e.g. find originals with a child in error).
Queue Status	Not Queued, Queued, New, or Processing — whether the file currently has a job in the file queue.
Metadata Status	Has Metadata (both metadata and technical_metadata are set) or Has No Metadata (either is empty).
Parents	Also show the parents (originals) of the matching files.
Children	Also show the children (versions) of the matching files.
Offset / Limit	Paging: the start offset and the page size (10 – 1000).

Expanding Parents or Children builds a tree instead of a flat result. In that mode an action can only run on the files you tick individually, not on the whole search result (see File Actions).

File States

Automatic changes between different states, which are done by internal workflows, are done in order. Internal states ("Status") are grouped into API states ("Status API").

Step	Status	Status API	Description
1	pending	pending	The file is in the queue, but has not yet been picked up by any file worker
2	processing	processing	A worker is processing the file.
2	pending_produce_internal	processing	Queued to produce (render) the automatically generated versions.
2	pending_manual_produce_internal	processing	Queued to (re)produce a manually triggered version.
2	pending_original_produce_internal	processing	Queued to produce versions from the original.
2	pending_metadata_internal	processing	Queued to extract / calculate the file metadata.
3	sync	sync	Processing of the file in file workers is done. Further information are still calculated for the database. Files in this state can be exported.
3	pending_copy_internal	sync	Queued to copy the file into a storage location.
3	pending_move_internal	sync	Queued to move the file within storage.
3	pending_checksum	sync	Queued to verify the file checksum. Files in this state can be exported.
4	done	done	The file and all children have been successfully converted. Files in this state can be exported.
4	error	failed	There was an error during conversion. See Errors and solutions or more information and possible solutions.

File Actions

The following actions can be manually performed on files. Each action changes the state of the file. Depending on the current state of a file, not all actions can be performed, and not all states can be reached.

To perform an action, tick the files you want (and optionally their children), pick an action from the Action dropdown, and press Action. Hovering an option in the dropdown shows the same help text as below.

Resync

Internal name: resync

Resync originals and reproduce versions.

If the file is an original, resync will update automatically produced versions as necessary. File metadata is calculated only if it hasn't been produced yet. It does not repair versions in state error. Only versions in state done are considered for reproducing.

If the file is a version, it is rendered again, even if it is in state error already.

Resync on the entire search result is only allowed with an active filter and no parents and children selected.

Resync with metadata

Internal name: resync_force_metadata

Resync files with metadata. This works like "Resync", but forces the calculation of the metadata. This involves copying the file into the exec server directory which is slower than using the normal "Resync" action.

Resync with metadata (incl. request only)

Internal name: resync_force_metadata_incl_request_only

Resync files with metadata including request only recipes. This works like "Resync" but includes metadata recipes which are marked as request only.

Copy/Move & Produce

Internal name: copy_move_produce

Files which are stored remotely ("Remote Url" is set), can be copied into fylr storage using this action.

The "Produce Versions" flag is set and existing versions are deleted. With that, fylr starts rendering versions as defined in the produce configuration. This action can only be applied to originals.

Copy/Move

Internal name: copy_move

Files which are stored remotely ("Remote Url" is set), can be copied into fylr storage using this action. This action works like copy_move_produce but without producing versions.

This action can be applied to versions as well as to originals.

Produce Versions

Internal name: produce_versions

Remove all children of an original and resync to produce auto-generated versions.

Originals will be set to produce versions. This action works for all originals which are in a fylr storage location and have metadata. All versions (auto generated and not) will be deleted prior to the action.

If originals or versions are in the file queue, this action cannot be performed.

Check file checksums

Internal name: checksum

Checks the integrity of files that have been copied during a restore process. It parses the file reference which can include a sha224 or sha256 checksum that was read from the source instance, and compares it to the checksum of the local file. If they do not match, the file is set to state error.

Map to local storage

Internal name: map_to_local_storage

Adopts remote files that already live under a configured storage location, without copying any data. For every disk storage location that has a remote_url_prefix configured, this action sets the Location ID and Location Key of remote files whose Remote URL matches that prefix. If the remote URL ends in / + the file's mimetype, the mimetype is removed from the URL first.

The action is idempotent: it can be run repeatedly, and only files that actually change are updated and reported. This is the fast way to re-attach files after moving them onto a storage location's disk out of band — see the Map to local storage tutorial.

Applying an action to selected files or the whole result

Next to the Action dropdown, choose the target:

• Selected (N) — run the action on the files you have ticked. N updates as you select rows.

• Search result (M) — run the action on all M files matching the current filter, not just the current page. This option is only available with an active filter and with Parents and Children unchecked; when you are expanding a tree it is disabled.

Pressing Action asks for confirmation and then schedules the work — it does not run synchronously. Scheduling a very large selection (>100k) can take a while. Watch progress in the file queue and by reloading /inspect/files.

File Queue

Open <fylr url>/inspect/system/queues/?queue=file (or follow → Show file queue on the files page). The table shows queued file jobs as well as file jobs which are currently worked on. Each job is defined by a file in a specific state and the current action.

During the background processing of all file jobs, the queue can grow. This is because original files will produce a number of versions (depending on the recipe). Each new version creates new jobs, so once a single original file job is picked up by a file worker, for each file version which is to be produced, the queue will grow by the number of new jobs. The total number of jobs in the queue is always fluctuating, but should generally get lower over time.

File Locations

fylr can copy files to the local file system (location: local), or display files which are only stored with a URL (location: remote), and are then linked using this URL. Files which are on remote can be copied to local using the actions copy_move or copy_move_produce. The location of the file will then be changed. It is not possible to change a file location from local to remote.

In the file overview in the /inspect/files page, the files can be filtered by different locations:

• local (without from remote):

  • show all files which only are stored locally and which do not have been copied from a remote URL

• local (from remote):

  • show all files which are stored locally and which have been copied from a remote URL

• remote:

  • show all files which are not stored locally and which are only linked by a remote URL

• configured local locations:

  • filter by specific local locations, they are defined in the Location Manager

Errors and solutions

A file (or one of its versions) that could not be processed is left in status error (Status API failed). The Status Msg column carries the reason — truncated in the list, so hover it or open the file to read the full message. Filter by Status = error (or Child Status = error to find originals with a failed version) to list everything that needs attention.

The general fix is: read the Status Msg to find the cause, remove that cause, then re-run the matching action. A version in error is re-rendered by Resync (originals in error are not — reproduce their versions instead).

Status Msg / symptom	Cause	What to do
A version is in error with a message from the conversion tool	The exec-server recipe that renders this version failed — an unsupported or corrupt source, or the tool itself erroring	Open the file and read the full message. Confirm the source opens and the class/recipe is right, then Resync — the failed version is rendered again.
Version produced with filesize 0	The recipe produced an empty file	Resync the original. If it persists, check the exec-server logs and the recipe for that class/version.
Version produced without metadata	The version rendered, but its metadata could not be read	Resync with metadata to force metadata calculation.
A done original shows Metadata Status = Has No Metadata	Metadata was never calculated (e.g. imported without it)	Resync with metadata; for recipes marked request only, use Resync with metadata (incl. request only).
Checksum error after a restore	The local copy's checksum does not match the checksum recorded on the source	The copy is corrupt or incomplete — copy the file again (re-run the restore for it), then Check file checksums again.
A remote file will not copy (copy_move / copy_move_produce fails)	The Remote URL is unreachable, or the target storage location is down	Verify the Remote URL opens and the target location is connected in the Location Manager, then retry Copy/Move.
produce_versions does nothing on an original	The original is not in a fylr storage location, has no metadata, or still has a job in the file queue	Copy it into storage and give it metadata first (Copy/Move, then Resync with metadata), and wait for the queue to drain, then retry.

If a message does not match any of the above, it comes straight from the conversion tool for that file class; the fix is specific to that tool and source file. Once the cause is resolved, resync the affected files to clear the error.