Error Handling & Debugging

Debug Mode

Enable detailed logging to troubleshoot issues:

python
# Click with debug mode
click(driver, 'button.png', debug=True)

# Fill with debug mode
fill(driver, 'input.png', 'text', debug=True)

Debug Output Shows:

  • File existence validation
  • Element search attempts
  • Coordinates found
  • Clickability/fillability validation
  • Success/failure details

Common Errors & Solutions

File Not Found

text
[Pyxelator ERROR] Template image file not found: 'button.png'

Solution: Check file path, use absolute path, or verify file exists

Element Not Found

text
[Pyxelator ERROR] Element not found after 3 attempts: 'button.png'
[Pyxelator] Best match scored 0.42, below the 0.70 threshold.
[Pyxelator] That is a weak, partial match. Likely causes:
[Pyxelator]   - the template includes surrounding layout, not just the element
[Pyxelator]   - the element is styled differently now (hover, disabled, theme)

Solution: read the score on the second line. Since 0.5.0 the advice underneath it changes depending on how close the match was, so the right fix differs:

  • "That is close. Try confidence=0.68." - the element is there, rendered slightly differently. Use the suggested value.
  • "That is a weak, partial match." - the template caught more than the element. Recrop it tightly.
  • "almost certainly not on screen" - not a template problem. Check it has rendered, is scrolled into view, and nothing covers it.
  • "matched at 0.8x the template's size" - captured at a different window size, far enough out that automatic scaling cannot cover it. Recapture.

Template Cannot Be Matched At All

text
[Pyxelator] The template could not be matched at all. Usually one of:
[Pyxelator]   - it is a solid block of one colour, with no detail to match on
[Pyxelator]   - it is larger than the screenshot at every size tried
[Pyxelator]   - the file is not a readable image

Solution: a single-colour template is rejected on purpose. With no variation in it, the maths behind matching reports a perfect score at every position on the page, so it would "match" anywhere. Capture something with an edge, an icon or text in it.

Template Larger Than The Screenshot

text
[Pyxelator] The template (1920x893) is larger than the screenshot (1280x720).
[Pyxelator] It looks like a screenshot of the whole page rather than of one
[Pyxelator] element. Crop it down to just the button or field.

Solution: exactly what it says.

Element Not Clickable

text
[Pyxelator ERROR] Element is not clickable
[Pyxelator] Found: <DIV> "Some text..."

Solution: Recapture a smaller screenshot focused on the actual button

Element Not Fillable

text
[Pyxelator ERROR] Element is not fillable
[Pyxelator] Found: <BUTTON> "Submit"

Solution: Ensure template captures an input/textarea field, not a button

Retry Mechanism

Configure retry attempts for flaky elements:

python
# Retry up to 5 times with 1 second delay
click(driver, 'button.png', retries=5, delay=1.0)