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