> For the complete documentation index, see [llms.txt](https://docs.fylr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fylr.io/for-system-administrators/inspect/files.md). # Files ## The `/inspect/files` page Open `/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](#file-actions). | | **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](#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](#file-locations). | | **Status** | Restrict to one internal [status](#file-states). | | **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). | {% hint style="info" %} 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-actions)). {% endhint %} ## 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").
StepStatusStatus APIDescription
1pendingpendingThe file is in the queue, but has not yet been picked up by any file worker
2processingprocessingA worker is processing the file.
2pending_produce_internalprocessingQueued to produce (render) the automatically generated versions.
2pending_manual_produce_internalprocessingQueued to (re)produce a manually triggered version.
2pending_original_produce_internalprocessingQueued to produce versions from the original.
2pending_metadata_internalprocessingQueued to extract / calculate the file metadata.
3syncsync

Processing of the file in file workers is done. Further information are still calculated for the database.

Files in this state can be exported.

3pending_copy_internalsyncQueued to copy the file into a storage location.
3pending_move_internalsyncQueued to move the file within storage.
3pending_checksumsyncQueued to verify the file checksum. Files in this state can be exported.
4donedone

The file and all children have been successfully converted.

Files in this state can be exported.

4errorfailedThere 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](/for-system-administrators/migration/restore.md) 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](/help/tutorials/for-system-administrators/migrate-map-to-local-storage.md) 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](/for-system-administrators/inspect/system.md) and by reloading `/inspect/files`. ## File Queue Open `/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`](#copymove) or [`copy_move_produce`](#copymove--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](/for-administrators/location-manager.md) ## 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](/for-system-administrators/migration/restore.md) | 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](/for-administrators/location-manager.md), 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`.