Should V3 fingerprint_inputs() include normal node inputs, or only external state?

[jeremysim42]

I'm migrating a custom node to the V3 API and I'm a little confused about fingerprint_inputs().

Suppose my node has normal widget inputs like:

inputs=[
    io.String.Input("path"),
    io.Float.Input("strength", default=1.0),
]

Do I need to include path and strength in the value returned by fingerprint_inputs() so that changing them invalidates the cached output?

For example:

@classmethod
def fingerprint_inputs(cls, path, strength):
    return (path, strength)

Or does ComfyUI already include ordinary prompt/widget inputs in its cache key?

If they're already tracked, is fingerprint_inputs() intended mainly for state that can change without the workflow input changing, such as a file being modified on disk while its path stays the same?

For example, if the workflow contains:

file = "clip.mp4"

but clip.mp4 is later replaced or modified on disk, would that be the kind of situation where fingerprint_inputs() should return something like the file's modification time or content hash?

In other words, is the intended distinction roughly:

Normal widget/prompt input changes
    -> already detected by ComfyUI

Upstream connected node changes
    -> already detected by ComfyUI

External state changes while the workflow inputs remain identical
    -> use fingerprint_inputs()

I'm trying to understand whether including ordinary node inputs again in fingerprint_inputs() is redundant, or whether there are cases where they should be included explicitly.

[haowern98]

You generally do not need to include normal node inputs again in fingerprint_inputs().

ComfyUI already includes ordinary non-linked inputs in the node's cache signature. It also tracks linked upstream nodes through their signatures. So if path or strength changes normally, that change is already enough to invalidate the cached result.

For example, this would usually be redundant:

@classmethod
def fingerprint_inputs(cls, path, strength):
    return (path, strength)

The main purpose of fingerprint_inputs() is to account for state that can change without the workflow inputs themselves changing.

A file is a good example.

Suppose the node input is:

path = "clip.mp4"

If the workflow still contains exactly the same string, ComfyUI sees the normal input as unchanged. But the contents of clip.mp4 may have changed on disk.

In that case, you could fingerprint the file's modification time:

@classmethod
def fingerprint_inputs(cls, path, **kwargs):
    return os.path.getmtime(path)

or, if you need stronger change detection, return a hash of the file contents.

So the distinction is roughly:

Normal widget/prompt value changes
    -> already handled by ComfyUI

Linked upstream node changes
    -> already handled by ComfyUI

External state changes while the workflow inputs remain identical
    -> use fingerprint_inputs()

So for your example, I would not include (path, strength) merely to make normal input changes invalidate the cache.

If path points to mutable external data, then fingerprint the state of that data instead — for example its modification time, size, or content hash.

One practical tradeoff: using mtime is cheap, while hashing the entire file is more reliable but can be expensive for large files.