This guide helps you resolve runtime errors and environment-related issues when using AskUI.

​
Python Vision Agent Errors

​
Session Info Doesn’t Match Error

Error Message: 
grpc._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with:
status = StatusCode.PERMISSION_DENIED
details = "Session info doesn't match."
Cause: This happens when there’s a mismatch between your client session and the AskUI Controller session. Solution:
  1. Open Terminal/PowerShell
  2. Enter askui-shell
  3. Import debug commands: 
    AskUI-ImportDebugCommands
  4. Stop all running controllers: 
    AskUI-StopProcess -All
  5. Try your script again

​
Controller Connection Issues

Symptoms:
  • Timeout errors when starting agent
  • “Cannot connect to controller” messages
Solutions:
  1. Verify controller is running: 
    # In askui-shell
AskUI-ShowControllers
  2. Start controller if needed: 
    AskUI-StartController
  3. Check controller logs: 
    AskUI-ShowProcess

​
Environment Configuration

​
Python Path Issues

Problem: Python packages not found or wrong Python version used. Solutions:
  1. Use askui-shell Python environments: 
    # Create dedicated environment
AskUI-NewPythonEnvironment -Name "myproject"

# Activate it
AskUI-EnablePythonEnvironment -Name "myproject"

# Verify
AskUI-ShowInstalledPythonPackageVersion -PackageName "askui"
  2. Use virtual environments: 
    # Create virtual environment
python -m venv askui_env

# Activate (Windows)
askui_env\Scripts\activate

# Activate (macOS/Linux)  
source askui_env/bin/activate

​
Credential Configuration Errors

Problem: Missing or invalid workspace credentials. Solutions:
  1. Using askui-shell (recommended):
    • Credentials are automatically loaded
    • Run AskUI-ShowSettings to verify
  2. Using .env files: 
    # Install python-dotenv
pip install python-dotenv

# Create .env file
ASKUI_WORKSPACE_ID=your_workspace_id
ASKUI_TOKEN=your_token

# Load in script
from dotenv import load_dotenv
load_dotenv()
  3. Direct environment variables: 
    export ASKUI_WORKSPACE_ID=your_workspace_id
export ASKUI_TOKEN=your_token

​
Memory and Performance Issues

​
High Memory Usage

Symptoms:
  • System slowdown during automation
  • Out of memory errors
Solutions:
  1. Close agents properly: 
    # Always use context manager
with VisionAgent() as agent:
    # Your automation
    pass
# Agent automatically closed
  2. Limit concurrent agents: 
    # Run agents sequentially instead of parallel
for task in tasks:
    with VisionAgent() as agent:
        process_task(agent, task)

​
Slow Startup Times

Known Issue: ADE/Controller startup can be slow on some systems. Workarounds:
  1. Keep controller running: 
    # Start once and leave running
AskUI-StartController
  2. Pre-warm the system: 
    # Initialize once at start
def initialize_askui():
    with VisionAgent() as agent:
        agent.get("Test", response_schema=str)

# Run at application start
initialize_askui()

​
Platform-Specific Issues

​
Windows Service Errors

Problem: Controller fails to start as Windows service. Solutions:
  1. Run as administrator:
    • Right-click askui-shell
    • Select “Run as Administrator”
  2. Check Windows Defender:
    • Add AskUI to exclusions
    • Path: %USERPROFILE%\AppData\Local\Programs\askui

​
macOS Security Blocks

Problem: macOS blocks AskUI from running. Solutions:
  1. Grant permissions: 
    # Remove quarantine
xattr -d com.apple.quarantine /path/to/askui
  2. System Preferences:
    • Security & Privacy > Privacy > Accessibility
    • Add AskUI Controller

​
Linux Permission Errors

Problem: Permission denied errors. Solutions:
  1. Fix permissions: 
    chmod +x /opt/askui/bin/*
  2. Add user to required groups: 
    sudo usermod -a -G input $USER

​
Process Management

​
Zombie Processes

Problem: Old controller processes not cleaning up. Solutions:
  1. Clean up all processes: 
    # In askui-shell
AskUI-ImportDebugCommands
AskUI-StopProcess -All
  2. Manual cleanup (if needed): 
    # Find askui processes
ps aux | grep askui

# Kill specific process
kill -9 <PID>

​
Port Conflicts

Problem: Controller can’t start due to port in use. Default Ports:
  • Controller: 6769
  • UI Controller: 9000
Solutions:
  1. Find conflicting process: 
    # Windows
netstat -ano | findstr :6769

# macOS/Linux
lsof -i :6769
  2. Configure different port: 
    agent = Agent(controller_port=6770)

​
Debugging Runtime Issues

​
Enable Debug Logging

import logging

# Configure logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Now run your agent
with VisionAgent() as agent:
    agent.click("Button")  # Will show debug info

​
Capture System Information

# In askui-shell
AskUI-ShowVersions > system_info.txt
AskUI-ShowSettings >> system_info.txt
AskUI-ShowProcess >> system_info.txt

​
Common Error Patterns

ErrorLikely CauseSolution
Session doesn't matchStale controllerRestart controller
Connection refusedController not runningStart controller
Permission deniedInsufficient privilegesRun as admin/sudo
Module not foundWrong Python envCheck virtual env
Token invalidExpired credentialsRefresh token

​
Next Steps