Skip to content

Troubleshooting Guide

Common issues and solutions for DAMTools. Check this guide before reporting bugs.

Installation Issues

Add-on Not Appearing in List

Symptoms: DAMTools doesn't show up in the add-ons preferences.

Solutions: 1. Verify Download: Ensure you downloaded the correct .zip file 2. Installation Method: Use Install... button, don't extract the ZIP manually 3. File Integrity: Re-download if the file might be corrupted 4. Blender Version: Ensure you're using Blender 4.0 or newer 5. Restart Blender: Close and reopen Blender after installation

Import Errors on Enable

Symptoms: Error messages when trying to enable the add-on.

Solutions: 1. Check Console: Open Window → Toggle System Console for detailed errors 2. Update Blender: Use the latest stable Blender version 3. Clean Installation: Remove old DAMTools versions before installing new ones 4. Dependencies: Ensure all Python dependencies are satisfied 5. File Paths: Avoid special characters in folder names

Icons Not Loading

Symptoms: Tools appear with generic icons instead of custom DAMTools icons.

Solutions: 1. Restart Blender: Icons load during startup 2. Check Installation: Verify the assets/icons/ folder was included 3. Console Errors: Look for icon loading errors in the console 4. Permissions: Ensure Blender can read the addon folder 5. Memory: Close other applications if running low on RAM

Tool Issues

Tools Not Appearing in Pie Menu

Symptoms: Expected tools are missing from the pie menu.

Solutions: 1. Check Mode: Verify you're in the correct mode (Object/Edit) 2. Tool Visibility: Check preferences for disabled tools/categories 3. Selection: Some tools require specific object types selected 4. Poll Conditions: Tools may be disabled due to context requirements

Tool Execution Errors

Symptoms: Tools fail to run or produce unexpected results.

Solutions: 1. Object Selection: Ensure appropriate objects are selected 2. Object Type: Verify tools are being used on compatible object types (usually Mesh) 3. Mode Requirements: Check if tools require specific modes 4. Scene State: Some tools may conflict with certain scene configurations

Interactive Tools Not Responding

Symptoms: Modal tools don't respond to input or get stuck.

Solutions: 1. Escape Key: Press Esc to cancel modal operations 2. Input Focus: Ensure the 3D viewport has focus 3. Hotkey Conflicts: Check for conflicting hotkeys in keymap 4. Background Processing: Wait for heavy operations to complete

Performance Issues

Slow Tool Execution

Symptoms: Tools take a long time to complete operations.

Solutions: 1. Object Complexity: Reduce polygon count for faster processing 2. Scene Size: Consider working on isolated parts for complex scenes 3. System Resources: Close unnecessary applications 4. Tool Settings: Adjust tool parameters for faster execution 5. Hardware: Consider upgrading for very complex models

Memory Issues

Symptoms: Blender crashes or becomes unresponsive.

Solutions: 1. Save Frequently: Prevent data loss during testing 2. Reduce Scene Complexity: Work with simplified models 3. Close Other Apps: Free up system memory 4. Subdivisions: Avoid excessive subdivision levels 5. Batch Processing: Process large operations in smaller chunks

Interface Lag

Symptoms: Pie menu or interface elements respond slowly.

Solutions: 1. Disable Categories: Turn off unused tool categories 2. Reduce Icons: Use text-only mode if icons cause issues 3. Update Drivers: Ensure graphics drivers are current 4. Viewport Settings: Reduce viewport quality settings

Workflow Issues

Hotkey Conflicts

Symptoms: DAMTools hotkeys interfere with other add-ons or Blender defaults.

Solutions: 1. Keymap Editor: Customize hotkeys in Edit → Preferences → Keymap 2. Search Conflicts: Look for duplicate hotkey assignments 3. Context Awareness: Use mode-specific hotkeys when possible 4. Alternative Access: Use F3 search as backup access method

Tool Behavior Unexpected

Symptoms: Tools don't work as expected or documented.

Solutions: 1. Read Documentation: Check tool-specific documentation 2. Check Settings: Verify tool parameters and preferences 3. Default Settings: Reset tool settings to defaults 4. Version Differences: Ensure documentation matches your DAMTools version

Results Not as Expected

Symptoms: Tool output doesn't match what you intended.

Solutions: 1. Undo: Use Ctrl+Z to revert and try again 2. Parameter Adjustment: Modify tool settings before execution 3. Object Preparation: Ensure objects are properly prepared 4. Practice: Some tools require practice to master

Data Issues

Missing Tools After Update

Symptoms: Tools that worked before are no longer available.

Solutions: 1. Preferences Reset: Re-enable DAMTools after major updates 2. Clean Installation: Remove old version completely before updating 3. Settings Migration: Check if settings need to be reconfigured 4. Version Compatibility: Ensure update is compatible with your Blender version

Lost Preferences

Symptoms: Custom settings and preferences are reset.

Solutions: 1. Backup Settings: Export preferences before major updates 2. Settings Location: Check Blender's preferences folder 3. Manual Recovery: Re-configure critical settings 4. Version Notes: Check update notes for setting changes

Getting Help

Before Reporting Issues

  1. Update Everything: Ensure Blender and DAMTools are current
  2. Try Default Scene: Test with a fresh Blender file
  3. Reproduce Steps: Document exact steps to reproduce the issue
  4. Check Console: Note any error messages or warnings
  5. System Info: Note your OS, Blender version, and DAMTools version

Reporting Bugs

When reporting issues:

Include This Information: - Blender version (from Help → About Blender) - DAMTools version - Operating system - Exact steps to reproduce - Expected vs actual behavior - Console error messages - Screenshots/videos if relevant

Good Bug Report Example: 

Title: Extract Faces Interactive fails with high-poly objects

Environment:
- Blender 4.1.0
- DAMTools v2.1.0  
- Windows 11

Steps to Reproduce:
1. Import high-poly mesh (500k+ faces)
2. Run Extract Faces Interactive
3. Click on any face
4. Tool becomes unresponsive

Expected: Face selection should work normally
Actual: Tool freezes, must press Esc to cancel

Console Error: [Include any error messages]

Support Resources

  • Documentation: Check tool-specific pages for detailed usage
  • FAQ: Review this troubleshooting guide for common issues
  • Video Tutorials: Community-created content on YouTube
  • Contact Support: For persistent issues, contact DAMTools support

Performance Tip

When working with complex scenes, test tools on simplified versions first to avoid frustration with slow operations.

Updates

Many issues are resolved in newer versions. Always check for updates before extensive troubleshooting.