Skip to content

Common Issues

Quick solutions for frequently encountered ComfyGit problems.

This page helps you quickly diagnose and fix common issues. For each problem, you'll find a quick fix if it's simple, or a link to a detailed troubleshooting guide for complex issues.

Quick diagnosis table

Use this table to identify your issue and find the right solution:

Symptom Most Likely Cause Quick Fix
cg: command not found PATH not configured Restart terminal or fix PATH
Workspace not initialized No workspace created Run cg init
Environment 'X' not found Wrong env name or not created Check cg list or create with cg create
Dependency conflict error Incompatible package versions See Dependency Conflicts
No module named 'torch' Virtual environment broken Repair environment
Missing model in workflow Model not downloaded/indexed See Missing Models
uv resolution fails Package version incompatible See UV Errors
ComfyUI won't start Port conflict or corrupted env Check logs and repair
out of sync in status Config drift Run cg repair
Git errors (detached HEAD) Manual git operations See Environment Corruption

Installation issues

cg command not found

Problem: Running cg shows "command not found"

Diagnosis:

cg --version
# bash: cg: command not found

Solutions:

UV adds itself to PATH, but you need to restart your shell:

# Close terminal and open new one
# Or source the config manually:

# For bash
source ~/.bashrc

# For zsh
source ~/.zshrc

Verify UV is installed:

uv --version

If UV is missing, install it first.

# Ensure UV is working
uv --version

# Reinstall ComfyGit
uv tool install comfygit --force

# Verify
cg --version

UV tools should be in ~/.local/bin:

# Check if cg exists
ls -la ~/.local/bin/cg

# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

See the Installation guide for more details.

Workspace not initialized

Problem: Commands fail with "No workspace found"

Diagnosis:

$ cg list
✗ No workspace found. Initialize one with: cg init

Solution:

Initialize a workspace (required before using ComfyGit):

# Initialize in default location (~/comfygit)
cg init

# Or specify custom path
cg init /path/to/workspace

See Core Concepts - Workspace for more information.

Python version too old

Problem: Installation fails with "Requires Python 3.10+"

Solution:

Install Python 3.10 or newer:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.11

brew install python@3.11

Download from python.org

Then reinstall ComfyGit:

uv tool install comfygit --force

Environment issues

Environment not found

Problem: Commands fail with "Environment 'X' not found"

Diagnosis:

$ cg -e production status
✗ Environment 'production' not found

Solution:

Check available environments:

# List all environments
cg list

# If empty, create your first environment
cg create production

# If you meant a different environment
cg -e correct-name status

# Or set a default environment
cg use production
cg status  # Now uses 'production' by default

Environment won't start

Problem: cg run fails with import errors or module not found

Example errors:

ModuleNotFoundError: No module named 'torch'
ImportError: cannot import name 'X' from 'Y'

Diagnosis:

Check environment status:

cg status

Look for: - "Environment needs repair" - "Python packages out of sync" - "X nodes not installed"

Solution:

Repair the environment to fix virtual environment corruption:

# Preview what will change
cg repair

# Apply fixes
cg repair --yes

For severe corruption, see Environment Corruption.

"Out of sync" in status

Problem: cg status shows "Environment needs repair" or "out of sync"

Example:

⚠️  Environment needs repair:
  • 2 nodes in pyproject.toml not installed
  • 1 untracked node on filesystem
  • Python packages out of sync

Solution:

# Repair synchronizes your environment with config
cg repair --yes

This is the most common fix for environment issues. See Environment Corruption for details.

ComfyUI won't start

Problem: cg run starts but ComfyUI doesn't load in browser

Diagnosis steps:

  1. Check if ComfyUI is actually running: 

    # Check process
ps aux | grep comfyui

# Check port (default 8188)
lsof -i :8188

  2. Check logs for errors: 

    cg logs

# Or view live logs
cg logs --follow

Common causes:

Error in logs: Address already in use

Solution: 

# Find what's using the port
lsof -i :8188

# Kill the process
kill <PID>

# Or start on different port
cg run --port 8189

Error in logs: ModuleNotFoundError or import errors

Solution: 

cg repair --yes
cg run

Error in logs: "Cannot import node X" or "Node failed to load"

Solution: 

# Check which nodes failed
cg node list

# Remove problematic nodes
cg node remove problematic-node

# Or update them
cg node update --all

Custom node issues

Node installation fails

Problem: cg node add fails with errors

Common scenarios:

Dependency conflicts

Error message: 

✗ Dependency conflict detected
  • existing-node requires torch==2.0.0
  • new-node requires torch>=2.1.0

Solution: See Dependency Conflicts for comprehensive resolution strategies.

Quick fix: 

# Try updating existing node first
cg node update existing-node

# Then add new node
cg node add new-node

Node not in registry

Error message: 

✗ Node not found in registry: custom-node-name

Solution:

Add by git URL instead:

cg node add https://github.com/user/repo

Or search for correct name:

cg node search <partial-name>

Git clone failures

Error message: 

✗ Failed to clone repository
  fatal: could not read Username

Solution:

Check git authentication:

# Test git access
git ls-remote https://github.com/user/repo

# If private, authenticate with gh CLI
gh auth login

Node conflicts

Problem: Two nodes have conflicting names or directories

Example:

✗ Node conflict detected
  Directory 'comfyui-manager' already exists but points to different repository

Solution:

Follow the suggested actions in error message:

# Option 1: Remove old node
cg node remove old-node

# Option 2: Rename existing directory
mv custom_nodes/comfyui-manager custom_nodes/comfyui-manager-old

# Then retry
cg node add new-node

See Node Conflicts guide for details.

Workflow issues

Workflow shows missing nodes

Problem: cg workflow resolve reports missing custom nodes

Example:

⚠️  Partial resolution - issues remain:
  ✗ 2 custom nodes not found

Node issues:
  • comfyui-ipadapter-plus - not installed
  • comfyui-impact-pack - not installed

Solution:

Install missing nodes:

# Let ComfyGit find and install them
cg workflow resolve my_workflow

# Or install manually
cg node add comfyui-ipadapter-plus
cg node add comfyui-impact-pack

Workflow shows missing models

Problem: Workflow resolution reports models not found

Example:

⚠️  Partial resolution - issues remain:
  ✗ 2 models not found

Model issues:
  • sd_xl_base_1.0.safetensors - not in index
  • realistic_vision_v5.safetensors - not in index

Solution: See Missing Models for comprehensive fixes.

Quick fix:

# Sync model index (if you already have the models)
cg model index sync

# Or download missing models
cg model download https://civitai.com/api/download/models/XXXXX

Model issues

Models not appearing in index

Problem: Downloaded models don't show in cg model index list

Solution:

# Sync index to discover models
cg model index sync

# Verify models directory is set
cg model index status

# If no directory configured
cg model index dir ~/ComfyUI/models

See Missing Models for details.

CivitAI download fails (401 error)

Problem: Model downloads fail with "Unauthorized" or HTTP 401

Solution:

Set your CivitAI API token:

# Get token from: https://civitai.com/user/account
export CIVITAI_API_TOKEN='your-token-here'

# Make it permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export CIVITAI_API_TOKEN="your-token-here"' >> ~/.bashrc
source ~/.bashrc

# Retry download
cg model download <url>

See Missing Models - CivitAI authentication for details.

Python package issues

UV resolution fails

Problem: Adding nodes or packages fails with UV resolution errors

Example:

✗ Failed to resolve dependencies
  No solution found when resolving dependencies

Solution: See UV Errors for comprehensive troubleshooting.

Quick fixes:

# Try adding constraint for problematic package
cg constraint add "package-name>=1.0.0,<2.0.0"

# Repair environment
cg repair --yes

# If all else fails, update all nodes
cg node update --all

Package build failures

Problem: Installing nodes fails with "Build failed" or compiler errors

Example:

error: Failed to build: sageattention
  × Build failed with exit code 1
  ╰─> error: Microsoft Visual C++ 14.0 or greater is required

Solution:

Install build tools for your platform:

Install Microsoft C++ Build Tools

# Ubuntu/Debian
sudo apt-get install build-essential python3-dev

# Fedora
sudo dnf install gcc gcc-c++ python3-devel

xcode-select --install

See UV Errors - Build failures for details.

Getting detailed help

View logs

Logs contain detailed error information:

# View recent logs
cg logs -n 100

# View logs in real-time
cg logs --follow

# Logs location
~/.config/comfygit/logs/<env-name>-<timestamp>.log

Check environment status

Always start diagnosis with:

# Basic status
cg status

# Verbose output with full details
cg status --verbose

This shows: - Environment health - Sync status - Git state - Workflow issues - Uncommitted changes

Run verbose mode

Add --verbose to commands for detailed output:

cg node add <node> --verbose
cg repair --verbose
cg sync --verbose

Getting help from the community

If you're still stuck after trying these solutions:

  1. Check logs for detailed error traces: 

    cg logs -n 100

  2. Capture environment info: 

    cg status
cg --version
uv --version
python --version

  3. Search existing issues:

  4. GitHub Issues

  5. GitHub Discussions

  6. Report the issue with:

  7. ComfyGit version (cg --version)
  8. Full error message or log excerpt
  9. Steps to reproduce
  10. Output of cg status

Detailed troubleshooting guides

For complex issues, see these in-depth guides: