Troubleshooting¶

Comprehensive guide to diagnosing and resolving BlenderForge issues.

Table of Contents¶

• Quick Diagnostic Checklist
• Connection Issues
• AI Client Issues
• Installation Issues
• Asset Integration Issues
• AI Features Issues
• Performance Issues
• Error Messages Reference
• Debug Mode
• Log Files
• Platform-Specific Issues
• Getting Help

Quick Diagnostic Checklist¶

Run through this checklist before diving into specific issues:

1. Verify Installation¶

# Check BlenderForge is installed
blenderforge --version

# If not found, try:
python -m blenderforge --version
pip show blenderforge

2. Check Blender Setup¶

• Blender is running
• BlenderForge addon is enabled (Edit → Preferences → Add-ons)
• BlenderForge panel is visible (Press N, find tab)
• Server status shows "Connected"

3. Verify AI Client¶

• Config file exists and has valid JSON
• AI client has been restarted after config change
• BlenderForge appears in available tools

4. Test Connection¶

Ask your AI: "What objects are in my Blender scene?"

Connection Issues¶

"Could not connect to Blender"¶

Symptoms: - AI assistant reports connection failure - Tools return timeout errors - "Connection refused" messages

Solutions:

Solution 1: Verify Blender is Running¶

Make sure Blender is open and the addon is enabled before using BlenderForge tools.

Solution 2: Check Addon is Enabled¶

1. Go to Edit → Preferences → Add-ons
2. Search for "BlenderForge"
3. Ensure the checkbox is checked
4. If missing, reinstall the addon

Solution 3: Start the Server¶

1. Press N to open the sidebar in Blender
2. Go to BlenderForge tab
3. Click "Connect to MCP server"
4. Status should show "Connected"

Solution 4: Check Port Configuration¶

• Default port is 9876
• Verify the same port is set in:
• Blender's BlenderForge panel
• Your MCP configuration (if using BLENDER_PORT env var)

# Check if something else is using the port
# macOS/Linux
lsof -i :9876

# Windows
netstat -ano | findstr 9876

Solution 5: Check Firewall¶

• BlenderForge only uses localhost connections
• Some firewalls block localhost (127.0.0.1)
• Allow connections to 127.0.0.1:9876

"Connection refused"¶

Symptoms: - Error message contains "connection refused" - Tools fail immediately without timeout

Solutions:

Solution 1: Restart the Connection¶

1. In Blender's BlenderForge panel, click "Disconnect"
2. Wait 2-3 seconds
3. Click "Connect to MCP server"

Solution 2: Kill Stale Processes¶

# macOS/Linux - Find and kill process on port 9876
lsof -i :9876
kill <PID>

# Windows
netstat -ano | findstr 9876
taskkill /PID <PID> /F

Solution 3: Change Port¶

If port 9876 is persistently problematic: 1. In Blender panel, change port to 9877 2. Update your MCP config:

{
  "mcpServers": {
    "blenderforge": {
      "command": "blenderforge",
      "env": { "BLENDER_PORT": "9877" }
    }
  }
}

"Timeout waiting for Blender"¶

Symptoms: - Tools start but never complete - Error after 30-60 seconds

Solutions:

Solution 1: Simplify Operations¶

Instead of: "Create a detailed scene with 100 objects"
Try: "Add 10 cubes" then "Add 10 more cubes"

Solution 2: Check Blender Responsiveness¶

• Click in Blender's viewport
• If Blender is frozen, wait for it to recover or restart

Solution 3: Increase Timeout¶

# Set longer timeout (2 minutes = 120000ms)
export BLENDER_TIMEOUT=120000
blenderforge

Or in MCP config:

{
  "mcpServers": {
    "blenderforge": {
      "command": "blenderforge",
      "env": { "BLENDER_TIMEOUT": "120000" }
    }
  }
}

Solution 4: Check System Resources¶

• High RAM usage can slow Blender
• Close unnecessary applications
• Check for runaway processes

AI Client Issues¶

"Tools not appearing in AI assistant"¶

Symptoms: - AI doesn't recognize BlenderForge commands - No Blender tools in tools list - AI says "I don't have access to BlenderForge"

Solutions:

Solution 1: Restart AI Client¶

MCP servers load at startup. You must: 1. Close the AI client completely 2. Wait a few seconds 3. Reopen the AI client

Solution 2: Verify Config File Location¶

Solution 3: Validate JSON Syntax¶

{
  "mcpServers": {
    "blenderforge": {
      "command": "blenderforge"
    }
  }
}

Common JSON errors: - Missing commas between properties - Trailing commas (not allowed in JSON) - Unquoted strings - Wrong bracket types

Use a JSON validator: https://jsonlint.com/

Solution 4: Check Command Path¶

# Verify blenderforge is in PATH
which blenderforge  # macOS/Linux
where blenderforge  # Windows

# If not found, use full path in config:
{
  "mcpServers": {
    "blenderforge": {
      "command": "/usr/local/bin/blenderforge"
    }
  }
}

# Or use Python module:
{
  "mcpServers": {
    "blenderforge": {
      "command": "python",
      "args": ["-m", "blenderforge"]
    }
  }
}

Solution 5: Check AI Client Logs¶

Most clients have developer logs showing MCP errors:

• Claude Desktop: ~/Library/Logs/Claude/ (macOS)
• VS Code: Help → Toggle Developer Tools → Console
• Cursor: Help → Toggle Developer Tools → Console

"Tool calls fail silently"¶

Symptoms: - AI says it will use a tool but nothing happens - No visible error message - Blender doesn't respond

Solutions:

Solution 1: Check Blender Console¶

• Windows: Window → Toggle System Console
• macOS/Linux: Launch Blender from terminal:

  /Applications/Blender.app/Contents/MacOS/Blender  # macOS
  blender  # Linux
  

Solution 2: Enable Debug Logging¶

export BLENDERFORGE_DEBUG=true
blenderforge

Solution 3: Test Direct Connection¶

Ask AI to run a simple test:

"Get the Blender version"
"What is the name of the current scene?"

"MCP server failed to start"¶

Symptoms: - AI client shows server startup error - BlenderForge never connects

Solutions:

Solution 1: Check Python Environment¶

# Verify Python version
python --version  # Should be 3.10+

# Check if blenderforge is importable
python -c "import blenderforge; print('OK')"

Solution 2: Reinstall BlenderForge¶

pip uninstall blenderforge
pip install blenderforge

Solution 3: Check Dependencies¶

pip install "mcp[cli]>=1.3.0"

Installation Issues¶

"pip: command not found"¶

Solutions:

# Try pip3
pip3 install blenderforge

# Or use Python module
python -m pip install blenderforge
python3 -m pip install blenderforge

"Permission denied during installation"¶

Solutions:

# Install for user only
pip install --user blenderforge

# Or use virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows
pip install blenderforge

"blenderforge: command not found" after installation¶

Cause: pip installed to a directory not in PATH

Solutions:

# Find installation location
pip show blenderforge

# Add to PATH (example for user install)
# macOS/Linux - add to ~/.bashrc or ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"

# Or run as module:
python -m blenderforge

Python version incompatibility¶

Symptoms: - SyntaxError during import - ModuleNotFoundError

Solution:

# Check Python version
python --version

# BlenderForge requires Python 3.10+
# Install newer Python if needed

Asset Integration Issues¶

"PolyHaven not working"¶

Symptoms: - Can't search or download PolyHaven assets - "PolyHaven not enabled" errors

Solutions:

1. Enable PolyHaven Integration:
2. Open BlenderForge panel in Blender

3. Check Use PolyHaven checkbox

4. Check Internet Connection:

5. PolyHaven requires network access

6. Test: Visit polyhaven.com in browser

7. Check API Availability:

8. PolyHaven API: https://api.polyhaven.com

9. If API is down, wait and try later

10. Update BlenderForge:

    pip install --upgrade blenderforge
    

"Sketchfab not working"¶

Symptoms: - Authentication failures - "Invalid API key" errors

Solutions:

1. Verify API Key:
2. Log into sketchfab.com
3. Go to Settings → API
4. Copy the API token

5. Re-enter in BlenderForge panel

6. Check API Key Format:

7. Should be a long alphanumeric string

8. No spaces or special characters

9. Check Model Permissions:

10. Not all models are downloadable
11. Use downloadable: true filter
12. Check license requirements

"Hyper3D/Hunyuan3D generation fails"¶

Symptoms: - Generation starts but never completes - Authentication errors - Credit exhausted messages

Solutions:

1. Verify Credentials:
2. Double-check API key/secret

3. Ensure account is active

4. Check Credit Balance:

5. Hyper3D uses credits
6. Free trial may have limits

7. Check account dashboard

8. Check Generation Status:

9. AI generation takes 15-60+ seconds
10. Use status polling commands

11. Don't cancel too early

12. Check Rate Limits:

13. Some services have request limits
14. Wait between generation requests

AI Features Issues¶

"AI Material Generator not working"¶

Symptoms: - Material generation fails - No material created in Blender

Solutions:

1. Check Object Selection:
2. Material generator may require an object to be selected

3. Or specify target object name

4. Check Blender Console:

5. Look for Python errors during material creation

6. Common: missing node connections

7. Verify Scene Setup:

8. Ensure you're in a 3D scene (not compositor, etc.)
9. Check Blender is in Object mode

"Natural Language Modeling fails"¶

Symptoms: - Object not created as expected - Wrong position/size/color

Solutions:

1. Use Clearer Descriptions:

   Better: "Create a red cube at position (2, 0, 0) with size 1 meter"
   Worse: "Make something red over there"
   

2. Check Units:

3. Blender uses meters by default

4. Specify units explicitly when needed

5. One Operation at a Time:

   Instead of: "Create a red cube, blue sphere, and green cylinder"
   Try: Three separate commands
   

"Scene Analyzer returns empty results"¶

Symptoms: - No analysis returned - Generic or unhelpful feedback

Solutions:

1. Ensure Scene Has Objects:
2. Analyzer needs content to analyze

3. Add some objects first

4. Check Scene Complexity:

5. Very simple scenes may not trigger detailed analysis
6. More complex scenes get better feedback

"Auto-Rig not finding mesh"¶

Symptoms: - "Mesh not found" error - Armature not created

Solutions:

1. Verify Mesh Name:
2. Use exact mesh object name

3. Check Object name vs Data name in Blender

4. Check Mesh Type:

5. Must be a mesh object (not curve, text, etc.)

6. Humanoid rig needs humanoid-like mesh

7. Mesh Requirements:

8. Mesh should be at origin or specify location
9. Should have appropriate topology for rigging

Performance Issues¶

"Blender becomes slow/unresponsive"¶

Symptoms: - Blender UI freezes - High memory usage - Operations take too long

Solutions:

1. Reduce Operation Complexity:
2. Download smaller textures (2K instead of 8K)
3. Import simpler models

4. Process fewer objects at once

5. Manage Memory:

6. Close unnecessary panels
7. Purge orphan data: File → Clean Up → Purge All

8. Restart Blender periodically

9. Optimize Scene:

10. Use simpler materials for preview
11. Lower subdivision levels
12. Hide complex objects when not needed

"MCP server uses high CPU"¶

Symptoms: - High CPU from blenderforge process - System slowdown

Solutions:

1. Avoid Polling Loops:
2. Don't continuously check AI generation status

3. Wait between status checks

4. Restart MCP Server:

5. Restart your AI client

6. This restarts the MCP server process

7. Check for Stuck Operations:

8. Kill and restart if an operation is hanging

"Large scenes cause timeouts"¶

Solutions:

1. Increase Timeout:

   export BLENDER_TIMEOUT=300000  # 5 minutes
   

2. Work in Sections:

3. Process parts of the scene separately

4. Use collections to organize

5. Simplify Queries:

6. Get info about specific objects, not entire scene
7. Use filters to reduce data

Error Messages Reference¶

Python/Module Errors¶

"ModuleNotFoundError: No module named 'mcp'"¶

pip install "mcp[cli]>=1.3.0"

"ImportError: cannot import name 'FastMCP'"¶

pip install --upgrade "mcp[cli]>=1.3.0"

"ModuleNotFoundError: No module named 'blenderforge'"¶

pip install blenderforge
# Or if installed in virtual environment, activate it first

Connection Errors¶

"JSONDecodeError" in logs¶

Cause: Malformed messages between server and Blender

Solution: 1. Restart both Blender and AI client 2. Check Blender console for errors 3. Update to latest BlenderForge version

"Permission denied" when starting server¶

Cause: Port in use or permission issue

Solution:

export BLENDER_PORT=9877
blenderforge

"Address already in use"¶

# Find and kill process using the port
lsof -i :9876 | grep LISTEN
kill <PID>

Blender Errors¶

"Context is incorrect"¶

Cause: Operation called in wrong Blender context

Solution: Ensure proper mode (Object/Edit) and selection

"Operator poll failed"¶

Cause: Blender operator prerequisites not met

Solution: Check object selection, mode, and scene state

Debug Mode¶

Enable Debug Logging¶

# Environment variable
export BLENDERFORGE_DEBUG=true
blenderforge

# Or in MCP config
{
  "mcpServers": {
    "blenderforge": {
      "command": "blenderforge",
      "env": { "BLENDERFORGE_DEBUG": "true" }
    }
  }
}

Capture Debug Output¶

# Save logs to file
blenderforge 2>&1 | tee blenderforge_debug.log

# Or redirect stderr
blenderforge 2>blenderforge_error.log

View Real-time Logs¶

# Follow log output
tail -f blenderforge_debug.log

Log Files¶

Log File Locations¶

Blender Console Access¶

Windows:

Window → Toggle System Console

macOS:

/Applications/Blender.app/Contents/MacOS/Blender

Linux:

blender

Collecting Logs for Bug Reports¶

# 1. Enable debug mode
export BLENDERFORGE_DEBUG=true

# 2. Capture output
blenderforge 2>&1 | tee debug.log

# 3. Reproduce the issue

# 4. Include debug.log in bug report

Platform-Specific Issues¶

macOS¶

"Operation not permitted"¶

• Check System Preferences → Security & Privacy
• Allow terminal/Python access

"blenderforge: command not found" with Homebrew Python¶

# Add Homebrew bin to PATH
export PATH="/opt/homebrew/bin:$PATH"
# Or
export PATH="/usr/local/bin:$PATH"

Blender from App Store Issues¶

• App Store version may have sandboxing restrictions
• Download from blender.org instead

Windows¶

"Python not found"¶

• Reinstall Python with "Add to PATH" checked
• Or add manually:

  C:\Users\<username>\AppData\Local\Programs\Python\Python311\
  C:\Users\<username>\AppData\Local\Programs\Python\Python311\Scripts\
  

"Access denied" errors¶

• Run Command Prompt as Administrator
• Check antivirus isn't blocking

Path Issues¶

:: Use forward slashes or escape backslashes
"C:/Users/name/path"
"C:\\Users\\name\\path"

Linux¶

Snap/Flatpak Blender Restrictions¶

• Snap and Flatpak have sandboxed file access
• May not be able to access all directories
• Consider official tarball from blender.org

Permission Issues¶

# Check addon directory permissions
ls -la ~/.config/blender/4.0/scripts/addons/

# Fix if needed
chmod 755 ~/.config/blender/4.0/scripts/addons/

"externally-managed-environment" Error¶

# Use virtual environment
python -m venv venv
source venv/bin/activate
pip install blenderforge

# Or use pipx
pipx install blenderforge

Getting Help¶

Before Asking for Help¶

1. Check this troubleshooting guide
2. Search existing issues: GitHub Issues
3. Enable debug logging and collect logs
4. Try to reproduce with minimal setup

Creating a Bug Report¶

Include the following information:

**Environment:**
- OS: [e.g., Windows 11, macOS 14.0, Ubuntu 22.04]
- Python version: [output of `python --version`]
- Blender version: [e.g., 4.0.2]
- BlenderForge version: [output of `blenderforge --version`]
- AI client: [e.g., Claude Desktop, VS Code + Copilot]

**Description:**
[What you were trying to do]

**Expected behavior:**
[What you expected to happen]

**Actual behavior:**
[What actually happened]

**Steps to reproduce:**
1. [First step]
2. [Second step]
3. ...

**Error messages:**
[Copy any error messages]

**Debug logs:**
[Attach or paste debug log output]

Contact Channels¶

• GitHub Issues: Report bugs
• GitHub Discussions: Ask questions

Useful Resources¶

• MCP Specification
• Blender Python API
• Blender Stack Exchange