🪐 🔄 Prompt Queue Iterator:
PromptQueueIterator selects one prompt block from a collection each time the workflow runs. It can move through the collection in order, stop at the end, choose freely at random, or visit every block once in a shuffled cycle. It remembers its position between runs and can show progress in the interface, making it useful when you want to generate a series of images from different prompts without manually changing the workflow each time. If the same queued run is retried and its assignment is still remembered, the node reuses that run’s selection rather than advancing again.
🪐 🔄 Prompt Queue Iterator Input Parameters:
pop_mode
Controls how a prompt is selected. Options are Sequential (Loop on End) (default), which moves in order and returns to the first block after the last; Sequential (Stop on End), which moves in order and keeps selecting the last block once the end is reached; Random (Keep), which chooses a block at random on each new run without removing it; and Random (Cycle), which visits blocks in shuffled order within a cycle. This setting also affects how the remaining prompts are reported. There is no numeric minimum or maximum; choose one of the four listed options.
separator
Determines where one prompt block ends and the next begins. Options are >1 Empty Line (default), which splits at a blank line; Newline, which treats each nonempty line as a prompt; >2 Empty Lines, which requires at least two empty lines between blocks; and Custom Regex, which uses the pattern supplied in custom_regex. Choose a separator that matches how you have arranged your prompts, because changing it can change both the number of blocks and the prompts selected. There is no numeric minimum or maximum; choose one of the four listed options.
text
The required multiline text containing the prompts to divide into blocks. Its default is an empty string, and the source specifies no minimum or maximum length. With the default separator, for example, you can put a blank line between two image descriptions to make them separate prompts. Leading and trailing whitespace is removed from each resulting block, and empty blocks are skipped. If prompt is connected, its value takes precedence over this text.
custom_regex
An optional text pattern for defining your own block boundaries when separator is Custom Regex. Its default is an empty string, and the source specifies no minimum or maximum length. For example, the pattern \n---\n can split prompts separated by a line containing ---. If you select Custom Regex but leave this field blank, the node splits at blank lines. An invalid pattern also causes it to fall back to blank-line splitting and print a warning. This field does not control splitting when another separator option is selected.
track_by
Controls which changes create a separate saved position for this node. Options are Text & Node (default) and Node Only; there is no numeric minimum or maximum. Text & Node tracks position using the node, its full prompt text, and its selection and splitting settings, so changing those settings starts a separate sequence. Node Only keeps one position for the node across such changes. Use the default when you want a newly edited prompt collection to start independently; use Node Only when you deliberately want to continue from the existing position after an edit.
prompt
An optional connected string input for prompt text supplied by another node. It has no specified default, minimum, or maximum. When connected with a value, it takes precedence over text, including when that value is empty: an empty connected value produces no prompt rather than falling back to the text widget. Connect it when another part of your workflow builds or supplies the prompt collection.
🪐 🔄 Prompt Queue Iterator Output Parameters:
prompt
The selected prompt block as a string, ready to pass to another node in your workflow. It is empty when the effective input contains no usable prompt blocks. In sequential modes it follows the saved position; in random modes it reflects the block chosen for that run.
remaining_text
A string containing the prompt blocks after the selected block in the applicable order. Sequential modes use their original order, while Random (Cycle) uses the current shuffled order. Random (Keep) returns an empty string because it does not consume prompts or establish a remaining order. An empty value can also mean the selected block is last, so it does not always mean the node has stopped.
remaining_count
The number of blocks included in remaining_text, returned as an integer. It tells you how many selections remain after the current selection in the applicable sequential or shuffled order. In Random (Keep), it is always 0 because that mode does not track a remaining set. It is also 0 when the input has no usable blocks.
exhausted
A Boolean value indicating whether Sequential (Stop on End) has reached its last block. It becomes true when that last block is selected and remains true on later runs in that mode, which continue to output the last block. In other modes, and when there are no usable blocks, it is false. Treat this as an end-of-sequence signal, not as an indication that the prompt output has become empty.
🪐 🔄 Prompt Queue Iterator Usage Tips:
- For a planned image series, put each complete prompt in its own block and choose
Sequential (Loop on End)to repeat the series orSequential (Stop on End)to signal when the final prompt has been reached. - Choose
Newlinefor one short prompt per line. Keep the default blank-line separator when individual prompts need multiple lines. - Use
Random (Cycle)when you want shuffled variety across a cycle, andRandom (Keep)when repeats are acceptable on any run. - Keep
track_byatText & Nodeif editing your prompt list should start a separate sequence. ChooseNode Onlyonly when continuing the same saved position across text or separator changes is intentional. - When feeding prompts from another node, check that its connected
promptvalue contains the expected text; it overrides the localtextfield. - Use
exhaustedto detect the final selection in stop mode. Do not useremaining_count == 0as a universal stop test, becauseRandom (Keep)always reports zero.
🪐 🔄 Prompt Queue Iterator Common Errors and Solutions:
Invalid custom regex pattern '…': … Falling back to empty line separator.
- Explanation: The custom splitting pattern could not be compiled. The node prints this warning and splits at blank lines instead, which may produce a different number of prompts than you intended.
- Solution: Check the pattern’s brackets, parentheses, and backslashes, or select a built-in separator if you do not need a custom pattern.
Warning reading prompt iterator state: …
- Explanation: The node could not read its saved position. It prints a warning and proceeds without usable saved state, so the next selection may not continue where you expected.
- Solution: Check that the application can access its user-data location and inspect the reported file or permission problem. After fixing access, run the workflow again.
Error saving prompt iterator state: …
- Explanation: The node could not save its updated position. It prints an error, so later runs may repeat a selection instead of reliably continuing.
- Solution: Check available disk space and write permissions for the application’s user-data location, then rerun the workflow.
Empty prompt with remaining_count of 0
- Explanation: The effective input is empty or produces no nonempty prompt blocks. A connected
promptvalue takes priority over the localtextfield, even when the connected value is empty. - Solution: Check the upstream value if
promptis connected. Otherwise, add nonempty content totextand confirm thatseparatormatches its layout.
Prompt selection restarts after changing text or settings
- Explanation: With the default
Text & Nodetracking, the node uses a separate saved position when the prompt text, selection mode, separator, or custom pattern changes. - Solution: Keep those values consistent for one series. Select
Node Onlyif you intentionally want to carry the position across changes.
Last prompt repeats in Sequential (Stop on End)
- Explanation: This is the mode’s defined behavior: it reports
exhaustedastrueat the last block but continues to select that block on later runs. - Solution: Use the
exhaustedsignal in your workflow to recognize the end, or chooseSequential (Loop on End)if you want subsequent runs to return to the first prompt.
Random (Keep) shows no remaining prompts
- Explanation: This mode makes an independent random selection without consuming blocks, so
remaining_textis empty andremaining_countis0even though prompts are available. - Solution: Choose
Random (Cycle)if you need a shuffled sequence with a meaningful remaining count.
