Qontinuiontinui
← Back to Runner Documentation

Troubleshooting

Common issues and solutions for Qontinui Runner

Quick Diagnostics

Check Logs

Console output shows detailed error messages and stack traces

Verify Display

Ensure target application is visible on the correct monitor

Check Permissions

Runner needs screen capture and input control permissions

Validate Config

Ensure JSON configuration is valid and complete

Installation Issues

Windows: SmartScreen blocks installation

INSTALL_001

Symptoms:

  • •Windows protected your PC warning appears
  • •Installer won't run or gets blocked

Solutions:

  1. 1.Click More info on the SmartScreen dialog
  2. 2.Click Run anyway to proceed with installation
  3. 3.This is expected - the app is not yet code-signed ($200/year cost)
  4. 4.The software is safe and open source
Related Documentation →

Windows: Missing WebView2 Runtime (Development mode)

INSTALL_002

Symptoms:

  • •App won't launch after installation
  • •Error message mentions WebView2 or browser components

Solutions:

  1. 1.Download WebView2 Runtime from Microsoft: https://go.microsoft.com/fwlink/p/?LinkId=2124703
  2. 2.Run the installer
  3. 3.Restart Qontinui Runner
  4. 4.Note: Production .msi bundles WebView2, this only affects dev builds

macOS: App is damaged and cannot be opened

INSTALL_003

Symptoms:

  • •Error when trying to open the app after installation
  • •Gatekeeper shows damaged warning

Solutions:

  1. 1.This is Gatekeeper blocking unsigned apps
  2. 2.Right-click (or Control+click) the app icon
  3. 3.Select Open from the context menu
  4. 4.Click Open in the confirmation dialog
  5. 5.You only need to do this once per installation
Related Documentation →

Linux: Permission denied when running AppImage

INSTALL_004

Symptoms:

  • •AppImage won't execute
  • •Permission denied error in terminal

Solutions:

  1. 1.Make the AppImage executable: chmod +x qontinui-runner.AppImage
  2. 2.Run the AppImage: ./qontinui-runner.AppImage
  3. 3.Alternatively, right-click > Properties > Permissions > Allow executing as program

Linux: Missing dependencies for AppImage

INSTALL_005

Symptoms:

  • •AppImage fails to start with dependency errors
  • •Error mentions missing FUSE or libraries

Solutions:

  1. 1.Install FUSE: sudo apt install fuse libfuse2 (Ubuntu/Debian)
  2. 2.Or: sudo dnf install fuse fuse-libs (Fedora)
  3. 3.Install X11 libraries if missing: sudo apt install libx11-6 libxcb1
  4. 4.For Wayland users: Ensure XWayland is installed

Connection Issues

Unable to connect to Qontinui Web

CONN_001

Symptoms:

  • •Connection failed when trying to log in
  • •Runner can't fetch projects or configurations
  • •Authentication errors

Solutions:

  1. 1.Check your internet connection
  2. 2.Verify Qontinui Web is accessible in your browser: https://qontinui.io
  3. 3.Try logging out and back in
  4. 4.Check firewall settings - Runner needs HTTPS access
  5. 5.If using corporate network, ensure WebSockets are allowed

Authentication tokens not persisting

CONN_002

Symptoms:

  • •Runner asks you to log in every time you open it
  • •Session doesn't persist between launches

Solutions:

  1. 1.Windows: Check Windows Credential Manager access
  2. 2.macOS: Verify Keychain Access permissions for Qontinui Runner
  3. 3.Linux: Ensure Secret Service (libsecret) is installed and running
  4. 4.Try logging out, restarting the app, and logging in again

Token Storage

  • •Tokens stored in OS keychain: Windows Credential Manager, macOS Keychain, Linux Secret Service
  • •Service name: com.qontinui.runner
  • •Check if other apps using keychain work correctly

Device registration issues

CONN_003

Symptoms:

  • •Device not registered error
  • •Can't connect desktop runner to project

Solutions:

  1. 1.Ensure you've selected a project in Qontinui Web before connecting
  2. 2.Copy the connection string from Connect Desktop Runner page
  3. 3.Paste the full connection string into Runner
  4. 4.Check that your account has permission to access the project
  5. 5.Try regenerating the connection string if it's old
Related Documentation →

Execution Issues

Python executor fails to start

EXEC_001

Symptoms:

  • •Executor error in logs
  • •Failed to start Python process
  • •Runner appears frozen after loading config

Solutions:

  1. 1.Check Python 3.10+ is installed: python --version
  2. 2.Verify qontinui library is installed: pip show qontinui
  3. 3.Check logs for Python stack traces
  4. 4.Ensure no antivirus is blocking Python subprocess execution
  5. 5.Try restarting Runner completely

Python Bridge

  • •Runner spawns Python subprocess to execute automation
  • •Communication via stdin/stdout using JSON protocol
  • •Check .dev-logs/ for detailed Python output (dev mode)

Initial state not found

EXEC_002

Symptoms:

  • •Execution stops immediately after starting
  • •No initial state detected or Initial state not active

Solutions:

  1. 1.Verify at least one state has is_initial: true in your config
  2. 2.Check that the target application is in the expected initial state
  3. 3.Ensure initial state's identifying images match the current screen
  4. 4.Lower similarity thresholds if images aren't being recognized (try 0.8 instead of 0.9)
  5. 5.Use Find action to test image recognition before running workflow
Related Documentation →

Actions timing out repeatedly

EXEC_003

Symptoms:

  • •Actions fail with timeout errors
  • •Workflow execution is extremely slow
  • •Many retry attempts in logs

Solutions:

  1. 1.Increase default_timeout in config (try 15000ms for slow apps)
  2. 2.Add action_delay between actions to give UI time to respond (try 200-500ms)
  3. 3.Check if target app is waiting for user input or has modal dialogs
  4. 4.Look for loading animations or spinners that may be blocking interactions
  5. 5.Verify the app isn't frozen or unresponsive

Timeout Configuration

  • •default_timeout: Max time to wait for actions (default 10000ms)
  • •default_retry_count: Number of retry attempts (default 3)
  • •action_delay: Delay between actions (default 100ms)

Image recognition failing: Image not found on screen

EXEC_004

Symptoms:

  • •FIND actions repeatedly fail
  • •CLICK actions can't locate elements
  • •Low similarity scores in logs

Solutions:

  1. 1.Verify the image is actually visible on the current screen
  2. 2.Lower similarity threshold (0.8 or 0.75 instead of 0.9)
  3. 3.Recapture the image if the UI has changed
  4. 4.Check if image is outside the search region
  5. 5.Enable multi-scale search if screen resolution differs from capture
  6. 6.Look for overlapping windows or notifications covering the element
  7. 7.Verify correct monitor is selected for multi-monitor setups
Related Documentation →

State machine stuck: No applicable transitions found

EXEC_005

Symptoms:

  • •Workflow stops mid-execution
  • •No transitions are triggered from current state
  • •State machine appears frozen

Solutions:

  1. 1.Check that the current state has outgoing transitions defined
  2. 2.Verify transition conditions/triggers are met
  3. 3.Ensure to_state exists and is reachable
  4. 4.Review state history in logs to see how automation arrived here
  5. 5.Add error recovery transitions for common failure states
  6. 6.Use continue_on_error for actions that may fail

Execution too slow or hanging

EXEC_006

Symptoms:

  • •Workflow takes much longer than expected
  • •Runner appears to hang between actions
  • •High CPU usage during execution

Solutions:

  1. 1.Reduce default_retry_count if not needed (try 1 or 2 instead of 3)
  2. 2.Decrease action_delay for faster execution (try 50ms)
  3. 3.Use search regions to limit image search areas
  4. 4.Disable multi-scale search if not needed
  5. 5.Check for infinite loops in state transitions
  6. 6.Review process complexity - break into smaller steps
  7. 7.Ensure no background processes are competing for resources

Configuration validation errors

EXEC_007

Symptoms:

  • •Config fails to load with validation errors
  • •Missing images, invalid state references
  • •Malformed processes or actions

Solutions:

  1. 1.Check console output for specific validation errors
  2. 2.Verify all referenced states exist in the configuration
  3. 3.Ensure all image files are embedded or accessible
  4. 4.Check JSON syntax is valid (no trailing commas, etc.)
  5. 5.Verify action types are correct (CLICK, FIND, TYPE, etc.)
  6. 6.Test config in Qontinui Web mock execution first

Performance Issues

High CPU usage during execution

PERF_001

Symptoms:

  • •CPU usage spikes to 80-100%
  • •System becomes sluggish
  • •Fan noise increases significantly

Solutions:

  1. 1.Use search regions to reduce image search area
  2. 2.Disable multi-scale matching if not needed
  3. 3.Increase action_delay to reduce polling frequency
  4. 4.Close other resource-intensive applications
  5. 5.Check if antivirus is scanning Python/Runner processes
  6. 6.Consider upgrading hardware for complex automations

High memory usage

PERF_002

Symptoms:

  • •RAM usage climbs over time
  • •System runs out of memory
  • •Runner crashes after long executions

Solutions:

  1. 1.Restart Runner between long workflow executions
  2. 2.Clear screenshot capture directory periodically
  3. 3.Reduce number of images in configuration
  4. 4.Check for memory leaks in custom actions
  5. 5.Close unnecessary applications to free RAM

Slow startup time

PERF_003

Symptoms:

  • •Runner takes 10+ seconds to open
  • •Loading screen appears for extended time

Solutions:

  1. 1.This is normal - Python executor initialization takes time
  2. 2.Ensure SSD is used for Runner installation (not HDD)
  3. 3.Check for antivirus scanning delaying startup
  4. 4.Close other applications using Python interpreters

Platform-Specific Issues

Windows

Screen capture permissions denied

Go to Settings > Privacy > Screenshots and apps. Allow Qontinui Runner.

Input control not working

Run Runner as administrator (right-click > Run as administrator) if automating elevated apps.

WebView2 Runtime not found

Download from https://go.microsoft.com/fwlink/p/?LinkId=2124703 and install.

macOS

Screen recording permission denied

System Preferences > Security & Privacy > Privacy > Screen Recording. Check Qontinui Runner.

Accessibility permission denied

System Preferences > Security & Privacy > Privacy > Accessibility. Add Qontinui Runner.

App won't open on Apple Silicon

Download the universal binary .dmg. Right-click > Open first time.

Linux

X11 display errors

Ensure DISPLAY environment variable is set. Try: export DISPLAY=:0

Wayland compatibility issues

Install XWayland: sudo apt install xwayland. Some features may require X11.

libfuse2 not found

Install FUSE: sudo apt install fuse libfuse2 (Ubuntu/Debian)

Error Codes Reference

Runner uses structured error codes for easier debugging. Look for these in console logs:

CONFIG_001Configuration Error
EXEC_001Executor Error
IO_001File System Error
JSON_001Data Format/Parse Error
PROC_001Process Error
COMM_001Communication Error
STATE_001Invalid State Error
VAL_001Validation Error
TIME_001Timeout Error
HEALTH_001Health Check Error

Advanced Debugging

Enable Verbose Logging

  1. 1.Open Runner settings
  2. 2.Enable Debug Mode or Verbose Logging
  3. 3.Restart execution and check console output
  4. 4.Look for detailed action logs and image recognition scores

Capture Execution Screenshots

  1. 1.Enable Screenshot Capture in settings
  2. 2.Run your automation workflow
  3. 3.Check the screenshots folder for before/after action images
  4. 4.Review screenshots to see exactly what the automation saw

Test Individual Actions

  1. 1.Use Run Specific Process mode instead of full workflow
  2. 2.Test each action in isolation
  3. 3.Verify image recognition with FIND before using CLICK
  4. 4.Check action parameters and timing

Review Python Logs (Development)

  1. 1.Check .dev-logs/runner-backend.log for Rust/Python errors
  2. 2.Check .dev-logs/qontinui-lib.log for library-level logs
  3. 3.Look for stack traces and Python exceptions
  4. 4.Verify Python subprocess is communicating correctly

Still Having Issues?

If you've tried the solutions above and still need help:

Check Documentation

Review other Runner documentation sections for detailed guides

Runner Documentation

Community Support

Ask questions and get help from the Qontinui community

GitHub Discussions ↗

Report a Bug

Found a bug? Report it on GitHub with logs and reproduction steps

Create Issue ↗

Contact Support

Need direct assistance? Reach out to our support team

support@qontinui.io

When reporting issues: Include your OS version, Runner version, error codes from logs, and steps to reproduce. This helps us fix problems faster.

Troubleshooting - Qontinui Runner Documentation