Kneelawk/Cats-Blender-Plugin
1
0
Fork 0
Code Issues 1 Pull requests 1 Projects Releases 117 Packages Wiki Activity Actions
Page: Troubleshooting
Pages
Bone Parenting Custom Model Creation Eye Tracking FAQ Home Installation MMD Options Optimization Other Options Quick Access Scaling Settings Troubleshooting Version Support Visemes
2 Troubleshooting
Yusarina edited this page 2025-11-15 21:37:39 +00:00
Table of Contents

Troubleshooting

Common issues and solutions for Cats Blender Plugin.

Quick Troubleshooting

💡 First Steps: Before diving into specific issues:

  1. Make sure you're using Blender 5.0 or above
  2. Verify you have the latest version of Cats
  3. Restart Blender after installing/updating Cats
  4. Check that Cats is enabled in Extensions preferences

Installation Issues

Extension Doesn't Appear After Installation

Symptoms:

  • Installed Cats but can't find it
  • No Cats tab in sidebar
  • Extension not in list

Solutions:

  1. Check if Enabled:

    • Edit > Preferences > Extensions
    • Search for "Cats"
    • Ensure checkbox is checked

  2. Restart Blender:

    • Close Blender completely
    • Reopen Blender
    • Check again

  3. Verify Installation:

    • Make sure you installed the ZIP file (don't extract it)
    • Verify you used "Install from Disk"
    • Check you downloaded the Blender 5.0 version

  4. Check Blender Version:

    • Help > About Blender
    • Must be 5.0 or above
    • Download correct Cats version for your Blender

5: Ensure the sidebar is open by pressing N

Installation Gives Errors

Possible Causes:

  • Wrong Cats version for your Blender
  • Corrupted download
  • Permission issues
  • Conflicting extensions

Solutions:

  1. Verify Version Match:

  2. Re-download:

    • Delete partial download
    • Download fresh copy
    • Verify file isn't corrupted

  3. Check Permissions:

    • Ensure Blender can write to extensions folder
    • Run Blender as administrator (Windows)
    • Check folder permissions

  4. Remove Conflicting Extensions:

    • Old Cats versions
    • Incompatible add-ons (Like MMD Tools, cats comes with the latest MMD Tools, there will conflict with each other)
    • Restart after removal

Cats Tab Not Visible in Sidebar

Solutions:

  1. Press N:

    • In 3D Viewport, press N key
    • Toggles sidebar visibility

  2. Look for Cats Tab:

    • Check all tabs in sidebar
    • Should see "Cats" tab
    • Click to open

  3. Verify Extension is Enabled:

    • Edit > Preferences > Extensions
    • Find Cats
    • Check enabled checkbox

Import/Export Issues

Model Won't Import

Symptoms:

  • Import button does nothing
  • Error messages during import
  • Blender crashes

Solutions:

  1. Check File Format:

    • Verify supported format (.pmx, .pmd, .fbx, .vrm, etc.)
    • File isn't corrupted
    • File size is reasonable

  2. Check File Path:

    • No special characters in path
    • Path isn't too long
    • File isn't in use by another program

  3. Try Blender's Native Importer:

    • File > Import
    • If that fails, file may be corrupted

  4. Check Console for Errors:

    • Window > Toggle System Console
    • Look for error messages
    • Report specific errors

Model Display Issues

Model Appears Black or No Textures

Symptoms:

  • Model is all black
  • Textures don't show
  • Materials look wrong

Solutions:

  1. Switch Viewport Shading:

    • Press Z key
    • Select "Material Preview" or "Rendered"
    • "Solid" mode may not show textures

  2. Check Material Properties:

    • Select mesh
    • Open Material Properties panel
    • Verify materials exist
    • Check if textures are loaded

  3. Texture Paths:

    • Materials may reference missing textures
    • Relink textures if needed
    • Use "Find Missing Files" in Blender

  4. After Material Combiner:

    • This is sometimes expected in Blender
    • Set up materials properly in Unity
    • Check Material Combiner troubleshooting

Model is Inverted/Inside Out

Symptoms:

  • Mesh appears inside-out
  • Backfaces showing
  • Shading looks wrong

Solutions:

  1. Recalculate Normals:

  2. Check in Edit Mode:

    • Tab to Edit Mode
    • Enable Face Orientation (overlay)
    • Blue = correct, Red = inverted

  3. Flip Normals if Necessary:

    • Select all faces
    • Use "Flip Normals" in Other Options
    • Only if entire mesh is inverted

Wrong Scale in VRChat/Unity

Symptoms:

  • Avatar too big or too small
  • Not at expected height
  • Proportions wrong

Solutions:

  1. Check Scale in Blender:

    • Use Scaling panel
    • Measure actual height
    • Scale to correct size (160-180cm recommended)

  2. Apply Transformations:

  3. Unity Import Scale:

    • Should be 1.0 for FBX
    • Check import settings in Unity
    • Don't scale in Unity, scale in Blender

Feature-Specific Issues

Eye Tracking Not Working

Symptoms:

  • Eyes don't move
  • Blinking doesn't work
  • Setup seems broken

Solutions:

  1. Verify Bone Selection:

    • Eye Tracking panel
    • Check head, left eye, right eye bones selected
    • Use correct bones

  2. Check Weight Painting:

    • Eyes must be weighted to eye bones
    • 100% weight recommended
    • No weight bleeding

  3. Test in Blender:

    • Use test controls in Eye Tracking panel
    • Verify eyes move
    • Check blinking shape keys

  4. Material Combiner Order:

    • Did you run Material Combiner after eye tracking?
    • Set up eye tracking after material combining
    • May need to redo setup

Visemes Don't Work

Symptoms:

  • Mouth doesn't move for lip sync
  • Shape keys not assigned
  • Preview doesn't show movement

Solutions:

  1. Check Shape Key Assignment:

    • Visemes panel
    • Verify Mouth A, O, CH assigned
    • Use correct shape keys

  2. Verify Shape Keys Exist:

    • Select mesh
    • Open Shape Keys panel
    • Confirm mouth shape keys present

  3. Test with Preview:

    • Use preview in Visemes panel
    • Check each viseme individually
    • Adjust intensity if needed

  4. Translation Issues:

    • Translate shape keys before viseme setup
    • Don't translate after setup
    • May break references

Bone Merging Causes Issues

Symptoms:

  • Model breaks after bone merging
  • Weights look wrong
  • Animations broken

Solutions:

  1. Check Merge Settings:

    • Optimization panel
    • Start with lower merge ratio (0.5)
    • Enable "Keep Merged Bones" for safety

  2. Test Before Cleanup:

    • Merge bones first
    • Test thoroughly
    • Clean up only if merge is good

  3. Verify Armature After:

    • Check bone hierarchy
    • Test animations
    • Verify weights look correct

  4. Undo if Necessary:

    • Ctrl+Z to undo
    • Try different settings
    • Or work from backup

Material Combiner Issues

Materials Turn Black/White

Symptoms:

  • After Material Combiner, materials are black or white
  • Textures missing

Possible Causes:

  • Materials don't have assigned textures
  • Shader incompatibility
  • VRM addon version issues

Solutions:

  1. Check Textures:

    • Verify materials have textures assigned
    • Relink missing textures

  2. Note:

Atlas Missing Textures

Symptoms:

  • Not all textures appear in atlas
  • Materials merged but atlas incomplete

Possible Causes:

  • Textures are packed in .blend file
  • Non-English Blender version
  • Unsupported shader
  • Materials already share textures

Solutions:

  1. Unpack Textures:

    • File > External Data > Unpack Resources
    • Unpack All Into Files
    • Save to location of your choice

  2. Check Blender Language:

    • Must be set to English
    • Node names are language-specific
    • Switch to English and regenerate nodes

  3. Verify Shader Support:

    • Check Material Combiner documentation
    • Some shaders aren't supported
    • May need to change shader type

  4. Already Optimized:

    • If materials already share texture, won't be re-atlased
    • This is normal behavior

Pillow Installation Keeps Repeating

Symptoms:

  • Pillow installation prompt every time
  • Installation fails
  • Can't use Material Combiner

Possible Causes:

  • VPN interference
  • Windows Store Blender
  • Permission issues

Solutions:

  1. Disable VPN:

    • Turn off VPN temporarily
    • Try installation again

  2. Manual Installation (Windows):

    1. Navigate to Blender folder\5.0\python\bin
2. Copy this path
3. Press Win+R, type cmd.exe
4. In console:
   set PythonPath="Your\Copied\Path"
   %PythonPath%\python.exe -m pip install Pillow --user --upgrade

  3. Manual Installation (macOS):

    /Applications/Blender.app/Contents/MacOS/Blender -b --python-expr "__import__('ensurepip')._bootstrap()"
/Applications/Blender.app/Contents/MacOS/Blender -b --python-expr "__import__('pip._internal')._internal.main(['install', '-U', 'pip', 'setuptools', 'wheel'])"
/Applications/Blender.app/Contents/MacOS/Blender -b --python-expr "__import__('pip._internal')._internal.main(['install', 'Pillow'])"

  4. Avoid Windows Store, Snap, Flatpack and package managers Blender:

    • Download from blender.org instead or ust the steam version.
    • Windows Store version has permission issues and Linux Package manager build there own version with a different python version. This can cause issues.

Performance Issues

Cats Operations Very Slow

Symptoms:

  • Tools take minutes to complete
  • Hang or freeze during operations

Possible Causes:

  • Very complex model
  • Many objects/meshes
  • Slow computer

Solutions:

  1. Be Patient:

    • Complex operations take time
    • Cats is working
    • Check console for progress

  2. Simplify First:

    • Remove unnecessary objects
    • Join meshes before operations
    • Clean up model first

  3. Close Other Programs:

    • Free up RAM
    • Close browser, etc.
    • Give Blender resources

Error Messages

"No Armature Selected"

Solution:

  • Select your armature object
  • Must select armature, not mesh
  • In Object Mode

"No Mesh Found"

Solution:

  • Ensure meshes are present
  • Meshes must be parented to armature
  • Check object visibility

"Shape Keys Not Found"

Solution:

  • Verify mesh has shape keys
  • Check correct mesh is selected
  • Shape keys must exist for viseme/eye tracking

"Bone Not Found"

Solution:

  • Verify bone names
  • Refresh bone list
  • Check bone exists in armature

Policy Violation Warnings (Blender 5.0)

Symptoms:

  • Warnings about extension policies
  • Alerts about legacy methods

This is Expected:

  • Cats uses legacy methods for third-party addons
  • Warnings are safe to ignore
  • Everything still works correctly
  • No action needed

Getting Additional Help

Before Asking for Help

  1. Check This Page: Many issues covered here
  2. Read Relevant Wiki Pages: Feature-specific guides
  3. Try Search: Discord/GitHub for similar issues
  4. Verify Version: Using supported Blender 5.0+

When Asking for Help

Include:

  • Blender version (exact)
  • Cats version
  • What you're trying to do
  • What happens instead
  • Error messages (exact text)
  • Screenshots if relevant
  • Console output if available

Where to Get Help

  • Discord: Community chat and support
  • GitHub Issues: Bug reports and feature requests
  • This Wiki: Documentation and guides

What NOT to Report

  • Issues with unsupported Blender versions or blender versions which are not the blender.org or steam version (anything before 5.0 is not supported)
  • Third-party extension problems (Material Combiner, etc.)
  • General Blender questions (use Blender forums)
  • Feature requests without discussion first

Common Workflow Issues

Order of Operations Wrong

Many issues stem from wrong order:

Correct Order:

  1. Import model
  2. Fix MMD (if MMD model, fresh only)
  3. Translate names
  4. Apply transformations if needed
  5. Combine materials/Create atlas
  6. Set up eye tracking
  7. Set up visemes
  8. Final optimization
  9. Export

Key Point: Material Combiner BEFORE eye tracking and visemes!

Backup Management

Always Keep Backups:

  • Before major operations
  • After completing stages
  • Save incremental versions
  • Use version control if possible

Good Backup Practice:

my_model_01_import.blend
my_model_02_fixed.blend
my_model_03_optimized.blend
my_model_04_rigged.blend
my_model_05_final.blend

Related Pages:

Please do not report any issues for Blender version below 5.0