Load PixText Model:
PixTextModelLoader, displayed as “Load PixText Model” in the PixText category, prepares a PixText model for workflows that edit text within existing images. It supports standalone PixText weight files as well as complete model packages, allowing you to use the released models without manually assembling their configuration and font resources when using the supported standalone files. The node prepares a reference to the selected model rather than immediately loading all of its weights into GPU memory; loading happens when a later operation needs the model. During that loading process, PixText checks the package configuration and verifies files against recorded SHA-256 checksums to help detect missing, altered, or incompatible assets. Actual editing requires an NVIDIA CUDA GPU with FlexAttention support, and GPU loading is managed through ComfyUI.
Load PixText Model Input Parameters:
model_name
A required COMBO selection that identifies the PixText model you want to prepare. Its options are generated from models discovered in the configured PixText and diffusion model folders, including the standard locations ComfyUI/models/pixtext and ComfyUI/models/diffusion_models. The supported standalone filenames identified by the node are PixText-MeanFlow.safetensors and PixText-Teacher.safetensors; complete model packages can also be discovered and selected. For a standalone file, the loading process uses the configuration and fonts bundled with the extension for that filename. Your selection determines which model weights and corresponding package resources are used for subsequent PixText operations. The source does not explicitly set a default model, and there is no numeric minimum or maximum. If no models are discovered, the menu displays (install a model package), which is a placeholder rather than a usable model.
precision
A required COMBO selection, marked as an advanced setting, that controls the numerical format used for model weights during loading and subsequent processing. The available options are exactly bfloat16 and float32, with bfloat16 as the default; numeric minimum and maximum values do not apply. bfloat16 uses a lower-precision format that generally reduces model memory requirements compared with float32, making it a practical starting point for GPU workflows. float32 retains more numerical precision but requires more memory for the weights and may reduce performance depending on your hardware. Changing this setting does not select a different model variant or guarantee better visual results; it changes how the selected model’s numerical values are represented. The setting is stored when this node executes and applied when the model is actually loaded.
Load PixText Model Output Parameters:
model
A custom PIXTEXT_MODEL output containing a model handle for subsequent PixText operations. This handle records the selected model’s location and numerical precision and can later hold the loaded PixText pipeline and its ComfyUI model-management wrapper. It is not an image, a text prompt, or a general-purpose diffusion model output; connect it to compatible inputs that accept PIXTEXT_MODEL. Its importance is that it gives later operations access to the selected weights, configuration, rendering fonts, and inference settings through one connection. Receiving this output does not by itself confirm that every package file has been validated or that the model fits into GPU memory, because those checks and the actual weight loading occur when the handle is used.
Load PixText Model Usage Tips:
- For the simplest standalone-file setup, use the workflow’s missing-model download links or ComfyUI’s native download dialog, save
PixText-MeanFlow.safetensorsorPixText-Teacher.safetensorsinComfyUI/models/diffusion_models, and refresh the model selection. - Keep the supported standalone filenames unchanged. The loading code locates bundled configuration and fonts using the filename without its
.safetensorsextension, so renaming a file can prevent it from finding the corresponding resources. - Start with
precisionset tobfloat16to reduce model-weight memory requirements. Usefloat32when you specifically need to test higher numerical precision and have sufficient GPU memory; it is not a guaranteed image-quality upgrade. - Verify that your ComfyUI environment can use an NVIDIA CUDA GPU with FlexAttention support before building a larger PixText workflow. Selecting a model successfully does not establish that your hardware can run it.
- If you use a complete model package, preserve its directory structure, manifest, configuration files, fonts, and weights. The package is validated as a matching collection of files, not just as a weight file.
- Expect model-loading work when the first downstream operation needs the model, rather than when this loader returns its output. If an error appears at that stage, check both the selected model assets and your GPU environment.
- Allow sufficient GPU memory for the full model. The integration requests full model loading because native PixText modules do not implement ComfyUI’s partial weight casting, so do not rely on partial-loading behavior to make an otherwise oversized model fit.
Load PixText Model Common Errors and Solutions:
Use the workflow's missing-model download links, save PixText-MeanFlow.safetensors or PixText-Teacher.safetensors in ComfyUI/models/diffusion_models, then refresh. Complete model packages also work.
- Explanation: The selected
model_nameis not present in the models currently discovered by the node. This can happen if no model is installed, a previously selected file was moved, or the menu still shows the installation placeholder. - Solution: Download a supported model using the workflow’s links, save it with the expected filename in
ComfyUI/models/diffusion_models, and refresh the selection. Alternatively, install a complete model package in a configured discovery location and select it.
PixText requires an NVIDIA CUDA GPU with FlexAttention support
- Explanation: When a downstream operation requested the model, ComfyUI’s selected processing device was not a CUDA device. The PixText integration does not use CPU-only execution for editing.
- Solution: Run ComfyUI with a compatible NVIDIA GPU and a CUDA-enabled PyTorch environment. Check that ComfyUI detects the GPU and is not running in CPU mode; if your hardware does not support the required environment, use a compatible machine.
CUDA is unavailable; PixText editing requires a CUDA GPU
- Explanation: The underlying pipeline was asked to use CUDA, but PyTorch reported that CUDA was unavailable. This is a pipeline-level check; the standard node integration also performs its own device check before loading.
- Solution: Confirm that the NVIDIA driver and your PyTorch installation support CUDA and that the GPU is visible to the ComfyUI process. Restart ComfyUI after correcting the environment.
FileNotFoundError involving manifest.json, config.json, inference_config.json, or a bundled asset directory
- Explanation: The loading process could not find a required package resource. A complete package may be incomplete, or a standalone weight file may no longer match the bundled asset directory expected from its filename.
- Solution: Restore the complete package or reinstall the PixText extension’s bundled assets. For standalone weights, use the original supported filename and ensure that the extension includes the matching
comfyui/model_assetsdirectory.
Unsupported or invalid PixText manifest
- Explanation: The manifest does not declare
format_versionas1, or itsfilesentry is not the expected file-verification mapping. This indicates an unsupported or malformed package manifest. - Solution: Replace the package with a compatible, complete PixText release. Do not simply edit the version number, because the remaining package contents may still be incompatible.
Model package is missing bundled file: ...
- Explanation: A file listed in the manifest is missing at the location the loader checks. For standalone weights, the selected weight file is checked in place of the package’s
model.safetensors. - Solution: Read the filename at the end of the error and restore that file from the matching release. Preserve the package’s directory structure and verify that your weight download completed.
Model package SHA-256 mismatch: ...
- Explanation: A file’s checksum does not match the value recorded in the package manifest. The file may be incomplete, modified, corrupted, or from a different release or model variant.
- Solution: Download the named file again from the matching release, or reinstall the full matching package. For standalone weights, make sure the selected file is the correct release for its filename; do not bypass the check by changing the manifest.
Model manifest must verify ...
- Explanation: The manifest omits a file that PixText requires it to verify. Having the file on disk is not enough if its verification entry is absent.
- Solution: Restore the original manifest and associated files from a compatible package rather than manually adding unverified entries.
Unsupported PixText model configuration
- Explanation: The model configuration does not use
format_versionequal to1, or itsvariantis neitherteachernormeanflow. - Solution: Use a supported PixText package and keep its configuration paired with its original weights. If using a standalone file, restore the extension’s matching bundled configuration.
Model interval_conditioning must match the release variant
- Explanation: The configuration’s interval-conditioning setting does not match the declared model variant. The loader requires this setting to be enabled for
meanflowand disabled forteacher. - Solution: Restore the configuration supplied with the selected variant. Avoid mixing Teacher and MeanFlow package files or manually changing the variant to make an incompatible package load.
Model manifest must contain a model_id
- Explanation: The manifest is missing a nonempty text value for
model_id, which the pipeline uses as its package identifier. - Solution: Restore the manifest from the matching model release or reinstall the complete package. Avoid inventing an identifier to repair an otherwise uncertain package.
Unsupported PixText inference configuration
- Explanation: The inference configuration does not declare the supported
format_versionof1. PixText cannot safely use settings from an unsupported configuration format. - Solution: Replace the inference configuration with the version distributed alongside your selected model and matching extension assets.
Error(s) in loading state_dict for GroupJiT
- Explanation: During actual weight loading, the model’s weights do not match the architecture defined by its configuration. Additional details may mention missing entries, unexpected entries, or tensor-size mismatches.
- Solution: Restore a matched set of weights and configuration files from the same PixText release. Do not rename unrelated weights to a supported PixText filename.
CUDA out of memory
- Explanation: The GPU does not have enough available memory to load the full model or perform a later editing operation. This can occur after the loader has already returned a valid model handle.
- Solution: Use
bfloat16instead offloat32, close other GPU-heavy applications, and free memory used by other models where possible. If the model still cannot fit, use a GPU with more memory; this integration requests full model loading rather than partial weight casting.
