Sequential Image Loader (folder):
SequentialImageLoader loads one image at a time from a folder and advances through the available image files according to the selected sequence position. It is designed for batch-style workflows where you want to process a folder of images one by one across queued executions, without manually selecting a different file each time. Images are naturally sorted so numbered filenames generally appear in an intuitive order, and the sequence can optionally include nested folders or run in reverse. When the sequence reaches the final image, it wraps around to the beginning, allowing repeated queues to continue cycling through the collection. The node also provides information about the selected file and the complete sequence, making it easier to track which image is currently being processed.
Sequential Image Loader (folder) Input Parameters:
directory
This text value identifies the folder that the node scans for images. Enter a full or relative folder path, such as C:\path\to\folder. The node ignores surrounding spaces and quotation marks when interpreting the path, and returns an error if the folder does not exist, cannot be read, or contains no matching files. The default value is an empty string, which means you must provide a valid folder before loading an image. The displayed placeholder is C:\path\to\folder. The folder is scanned according to the selected filetype, and the include_subfolders setting determines whether only this folder or its nested folders are searched.
include_subfolders
This Boolean setting controls whether the scan includes folders inside directory. The default is False, so only image files directly inside the selected folder are considered. Set it to True to search recursively through nested folders as well. When enabled, files are ordered using their paths relative to the main directory, which provides a stable order across subfolders. Enabling this option is useful for organized image libraries, but it can increase the number of files in the sequence and may make the sequence longer than expected.
index
This integer selects the position of the image to load in the current ordered sequence. The default is 0, which selects the first image in forward order, or the last image when reverse is enabled. The minimum value is 0 and the maximum value is 2147483647; the step size is 1. The index is normally advanced by the node's queue control or related interface behavior, so each queued execution can select the next image. If the index is larger than the number of matching files, the node wraps it around using the sequence length, allowing very large or continuously increasing indexes to continue producing valid images.
filetype
This option determines which image file extensions are included in the scan. The default option is png. The available choices are the values defined by FILETYPE_CHOICES in the node, with all also supported to include all file types recognized by that choice configuration. Selecting a specific type keeps the sequence focused and prevents unrelated images from being included; selecting all is useful when a folder contains several supported image formats. The selected value affects the total number of files, the current index position, and the error message shown when no matching files are found. The exact individual entries inside FILETYPE_CHOICES are not included in the supplied node interface, so they should be read from the installed node version.
reverse
This Boolean setting controls the direction in which the ordered files are traversed. The default is False, labeled forward (first→last), so the first naturally sorted file is processed first and the last file is processed last. Set it to True to use reverse (last→first), which starts with the final file in the normal ordering and moves backward through the sequence. Reversing does not rename or modify files; it only changes their processing order. The setting is useful when you want to process the newest or last-sorted images first, or when you need to run the same folder in the opposite direction.
Sequential Image Loader (folder) Output Parameters:
image
This output contains the selected image as an IMAGE tensor suitable for connection to image-processing or image-generation nodes. The image is converted to RGB and its pixel values are represented in the standard normalized range from 0.0 to 1.0. The selected file is automatically corrected according to its embedded EXIF orientation information when applicable, so images from cameras and some editing applications should appear in their intended orientation. The output contains one loaded image, not the entire folder sequence.
mask
This output contains a MASK associated with the selected image. For images with transparency, the mask is derived from the alpha channel, with transparent areas represented as mask values of 1.0 and opaque areas represented as 0.0. For images without an alpha channel, the node returns an all-zero mask with the same image dimensions, indicating that no transparency mask is present. This output can be connected to compositing, masking, or inpainting workflows.
filename
This string contains only the name of the selected file, without its folder path, such as frame_0042.png. It is useful for displaying the current frame, building labels, or recording which source image produced a result. The filename reflects the actual selected file after ordering, filtering, and index wrapping have been applied.
index
This integer reports the zero-based position of the selected image in the active sequence. The first image has index 0. The value reflects the wrapped position actually used for loading, so it remains within the range from 0 to ``total
- 1
whenever files are available. Whenreverse`` is enabled, the index still identifies the position in the reversed sequence rather than the file's position in the original forward sequence.
total
This integer reports the number of image files found after applying the directory, include_subfolders, and filetype settings. It tells you how many files are available in the current sequence and can be used to monitor batch progress or determine when a complete pass has been processed. The value is always positive when the node succeeds; if no matching files are found, the node stops with an error instead of returning an image.
file_path
This string contains the absolute path to the selected image file, such as C:\path\to\folder\frame_0042.png. It is useful when another part of a workflow, log, or external process needs the exact source location rather than only the filename. The path points to the file actually loaded after filtering, ordering, reverse traversal, and index wrapping have been applied.
Sequential Image Loader (folder) Usage Tips:
- Place the images you want to process in one folder and use a consistent naming pattern such as
frame_0001.png,frame_0002.png, andframe_0003.pngso natural sorting produces the intended order. - Keep
include_subfoldersset toFalsewhen the folder contains unrelated subdirectories or when you need a simple, predictable single-folder sequence. Enable it when your image collection is intentionally organized into nested folders. - Leave
filetypeset topngwhen working with PNG assets, especially when transparency is important. Useallor another available file-type option only when you intentionally want multiple supported formats included. - Start
indexat0for the first image in forward order. The node wraps indexes automatically, so queued processing can continue cycling through the folder without manually resetting the value at the end. - Use
reversewhen you want to process the last-sorted files first. Remember that changing the direction changes which file corresponds to each sequence position. - Check
totalandindexin the outputs to monitor batch progress. For example, an index of7with a total of20means the eighth image in the active sequence is being processed. - Use
filenamefor readable labels andfile_pathwhen you need the complete source location for logging, metadata, or downstream file-related operations. - Keep the selected directory focused on the images needed for the workflow. Fewer unrelated files make the sequence easier to predict and reduce unnecessary scanning, especially when recursive subfolder scanning is enabled.
Sequential Image Loader (folder) Common Errors and Solutions:
[Sequential Image Loader] No PNG files found in: '...'
- Explanation: The selected folder does not contain any matching PNG files, or the folder path is incorrect, inaccessible, empty, or points to a file instead of a directory. The message uses the selected file type in uppercase, so another selected type may produce a different label.
- Solution: Confirm that
directorypoints to an existing folder, verify that the folder contains files with the selected extension, and check that the filename extensions match the selectedfiletypeoption. Enableinclude_subfoldersif the images are stored inside nested folders.
[Sequential Image Loader] No JPG files found in: '...'
- Explanation: The node was configured to search for JPG files but found none in the selected directory or its currently enabled search scope.
- Solution: Add supported JPG images to the folder, choose the file type that matches the files you have, or enable
include_subfolderswhen the images are located below the selected directory.
[Sequential Image Loader] No image files found in: '...'
- Explanation: This message is used when
filetypeis set toalland no recognized image files are found. The folder may be empty, the path may be invalid, or the files may use formats not supported by the node's configured file-type choices. - Solution: Check the directory path and place supported image files in it. If the images are in nested folders, enable
include_subfolders. If a particular format is needed, select its specific available file-type option instead ofall.
[Sequential Image Loader] No WEBP files found in: '...'
- Explanation: The node is filtering for WEBP files, but no matching files were found in the search location. The issue can also occur when the extension or selected file-type option does not match the actual files.
- Solution: Verify the files are valid WEBP images and that their extensions match the selected option. Check the directory and enable recursive searching if necessary.
PIL.UnidentifiedImageError
- Explanation: A file matched the selected extension but could not be recognized as a valid image by the image loader. This can happen when a file is damaged, incomplete, or merely has an image-like filename extension.
- Solution: Open the file in an image editor to confirm it is valid, re-export or replace it, and remove any damaged files from the scanned folder.
PermissionError
- Explanation: The application cannot read the selected directory or one of the image files because the operating system has denied access.
- Solution: Move the images to a directory that the application can read, adjust folder and file permissions, or run the application with an account that has access to the location. Avoid using a path that is only available to a different operating-system user.
FileNotFoundError
- Explanation: A file or directory was moved, renamed, or deleted after the directory was selected or while the workflow was running.
- Solution: Confirm that
directorystill exists, keep source files in place during processing, and refresh or rerun the workflow after restoring the missing file.
ValueError: ...
- Explanation: The node raises a
ValueErrorwhen its scan produces no matching files. It may also appear if an image cannot be decoded correctly by the image-loading process. - Solution: Read the complete message after
ValueError. If it begins with[Sequential Image Loader] No, correct the directory or file-type settings. Otherwise, inspect the selected image for corruption or unsupported content.
