Troubleshooting

🔧 Troubleshooting

Common issues and how to fix them.

Installation Issues

"python: command not found"

Problem: Python is not installed or not in PATH.

Solutions:

1. Install Python

   • Download from python.org
   • During installation, check "Add Python to PATH"

2. Try python3 instead

   python3 "Python code/butterfly.py"

3. Verify installation

   python --version

---

"No module named turtle"

Problem: Turtle module not found (rare, as it's built-in).

Solutions:

1. Check Python version

   python --version

   Make sure it's 3.x, not 2.x

2. Reinstall Python with standard library included

3. Try in IDLE

   • Open Python IDLE
   • File → Open → butterfly.py
   • Run → Run Module (F5)

---

Runtime Issues

Window Opens Then Immediately Closes

Problem: Missing turtle. done() or script error.

Solutions:

1. Check line 100 has:

   turtle.done()

2. Run from terminal (not double-clicking) to see errors:

   python "Python code/butterfly.py"

3. Add error handling:

   try:
       # ...  your code ... 
       turtle.done()
   except Exception as e:
       print(f"Error: {e}")
       input("Press Enter to close...")

---

Nothing Draws / Blank Screen

Problem: Drawing is happening too fast or color issue.

Solutions:

1. Check colors aren't matching:

   screen.bgcolor("black")
   pen.color("#ff69b4")  # Must be different from black! 

2. Slow down the drawing:

   UPDATE_EVERY = 1
   DELAY_SECONDS = 0.01

3. Check pen is down:

   pen.pendown()  # Should be on line 89

---

Drawing is Too Small/Large

Problem: Scaling issues or wrong parameters.

Solutions:

1. Adjust MARGIN:

   MARGIN = 0.95  # Use more of screen

2. Adjust STEP_DIVISOR:

   STEP_DIVISOR = 30  # Larger butterfly
   STEP_DIVISOR = 80  # Smaller butterfly

3. Check window size:

   screen.setup(width=900, height=900)  # Increase if needed

---

Drawing is Distorted/Stretched

Problem: Non-square window or wrong aspect ratio.

Solutions:

1. Use square dimensions:

   screen.setup(width=900, height=900)  # Equal width and height

2. Don't use widescreen:

   # BAD: screen.setup(width=1600, height=900)
   # GOOD: screen.setup(width=900, height=900)

---

Drawing Too Slow

Problem: Too many points or updates.

Solutions:

1. Reduce points:

   POINTS = 2000  # Instead of 5000

2. Update less frequently:

   UPDATE_EVERY = 50  # Instead of 8

3. Remove delay:

   DELAY_SECONDS = 0  # No pause

4. Fastest possible:

   POINTS = 2000
   UPDATE_EVERY = 2000  # Update only at end
   DELAY_SECONDS = 0

---

Drawing Too Fast / Can't See Animation

Problem: Updates happening too quickly.

Solutions:

1. Update more frequently:

   UPDATE_EVERY = 1  # Every point

2. Add delay:

   DELAY_SECONDS = 0.01  # 10 ms pause

3. Reduce speed (doesn't help with tracer off):

   # This WON'T work because tracer is off
   # pen.speed(1)

---

Mathematical Issues

Butterfly Looks Wrong

Problem: Formula was modified incorrectly.

Solutions:

1. Reset to original:

   r = math.exp(math.cos(t)) - 2 * math.cos(4 * t) - (math.sin(t / 12)) ** 5

2. Check parentheses:

   # WRONG:  math.sin(t / 12) ** 5
   # RIGHT: (math.sin(t / 12)) ** 5

3. Check operator:

   # WRONG: math.exp(math.cos(t)) + 2 * math.cos(4 * t)
   # RIGHT: math.exp(math.cos(t)) - 2 * math.cos(4 * t)

---

"NameError: name 'math' is not defined"

Problem: Missing import.

Solution:

Add at top of file:

import math

---

"Math domain error" or "ValueError"

Problem: Invalid mathematical operation.

Solutions:

1. Check for division by zero:

   # If you modified the formula, ensure no division by zero

2. Check formula is correctly typed

3. Reset to working version

---

Display Issues

Colors Look Different Than Expected

Problem: Color rendering or hex code issue.

Solutions:

1. Use valid hex codes:

   pen.color("#ff69b4")  # Must start with #

2. Use color names:

   pen.color("pink")  # Easier, but less precise

3. Test colors:

   # Test different colors
   print(turtle.colormode())  # Should be 1. 0 or 255

---

Turtle Cursor Visible

Problem: Pen visibility setting.

Solution:

pen = turtle.Turtle(visible=False)  # Line 22
# Or later:
pen.hideturtle()

---

Performance Issues

Computer Freezing/Lagging

Problem: Too many points or computer too slow.

Solutions:

1. Reduce POINTS:

   POINTS = 1000

2. Remove animation:

   UPDATE_EVERY = 5000
   DELAY_SECONDS = 0

3. Close other programs

---

"Not Responding" During Drawing

Problem: Normal! Python is busy drawing.

Solution:

• Wait - the program is working
• If it truly hangs for >2 minutes, restart
• Reduce POINTS for faster completion

---

File Issues

"No such file or directory"

Problem: Wrong path or not in correct directory.

Solutions:

1. Check current directory:

   pwd  # On Mac/Linux
   cd   # On Windows

2. List files:

   ls  # On Mac/Linux
   dir # On Windows

3. Navigate to correct folder:

   cd Butterflies-in-my-IDE
   cd "Python code"
   python butterfly.py

4. Use quotes for paths with spaces:

   python "Python code/butterfly.py"

---

Platform-Specific Issues

macOS: "Python quit unexpectedly"

Problem: Tkinter/turtle compatibility issue.

Solutions:

1. Use system Python 3:

   python3 "Python code/butterfly.py"

2. Install Python from python.org (not brew)

---

Windows: Encoding Errors

Problem: File encoding issues.

Solutions:

1. Save file as UTF-8 in your editor

2. Add encoding declaration at top:

   # -*- coding: utf-8 -*-

---

Linux: Display Issues

Problem: Tkinter not installed.

Solutions:

1. Install Tkinter:

   sudo apt-get install python3-tk  # Ubuntu/Debian
   sudo yum install python3-tkinter  # Fedora

---

Getting Help

Still Having Issues?

1. Check the error message carefully
2. Search the error on Google or Stack Overflow
3. Open an issue on GitHub with:
   • Your OS (Windows/Mac/Linux)
   • Python version (python --version)
   • Complete error message
   • What you were trying to do

Useful Debug Commands

# Add at various points to debug: 
print(f"min_x: {min_x}, max_x: {max_x}")
print(f"Scale:  {scale}")
print(f"Total points: {len(raw_points)}")

---

Quick Fixes Checklist

Before asking for help, try:

• Python 3.x is installed
• Running from correct directory
• All imports are at top of file
• turtle. done() is at the end
• Colors are different (pen ≠ background)
• Window dimensions are square
• Formula has correct parentheses
• No syntax errors (run in terminal to check)

---

Still stuck? Open an issue on GitHub! 🦋