Troubleshooting

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

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

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

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

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://app.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

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

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

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

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

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