Troubleshooting Guide

Common issues and solutions for Basic Agent Chat Loop.

Installation Issues
Command Not Found
Import and Module Errors
Agent Loading Issues
Configuration Issues
Terminal and Display Issues
Command History Issues
Performance Issues
Platform-Specific Issues

Installation Issues

Package not found on PyPI

Symptom: ERROR: Could not find a version that satisfies the requirement basic-agent-chat-loop

Solutions:

# Update pip to latest version
pip install --upgrade pip

# Try with explicit package name
pip install basic-agent-chat-loop

# Check if you have internet connectivity
ping pypi.org

Permission denied during installation

Symptom: ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied

Solutions:

# Use user install (recommended)
pip install --user basic-agent-chat-loop

# Or use virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install basic-agent-chat-loop

# As last resort, use sudo (not recommended)
sudo pip install basic-agent-chat-loop

SSL certificate errors

Symptom: SSL: CERTIFICATE_VERIFY_FAILED

Solutions:

# Update certificates (macOS)
/Applications/Python*/Install\ Certificates.command

# Or temporarily bypass SSL (not recommended for production)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org basic-agent-chat-loop

Dependency conflicts

Symptom: ERROR: pip's dependency resolver does not currently take into account all the packages that are installed

Solutions:

# Install in isolated environment
python -m venv fresh_env
source fresh_env/bin/activate
pip install basic-agent-chat-loop

# Or force reinstall
pip install --force-reinstall --no-cache-dir basic-agent-chat-loop

Command Not Found

"chat_loop: command not found" on macOS/Linux

Symptom: Shell cannot find the chat_loop command after installation

Diagnosis:

# Check if package is installed
pip show basic-agent-chat-loop

# Find where pip installed scripts
pip show -f basic-agent-chat-loop | grep -E "bin/|Scripts/"

# Check your PATH
echo $PATH

Solutions:

Add pip's bin directory to PATH:

# For bash (add to ~/.bashrc)
export PATH="$HOME/.local/bin:$PATH"

# For zsh (add to ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

Use full path temporarily:
```
~/.local/bin/chat_loop
```
Reinstall with system-wide access:
```
sudo pip install basic-agent-chat-loop
```

"chat_loop: command not found" on Windows

Symptom: PowerShell or CMD cannot find the command

Solutions:

Check if Scripts directory is in PATH:

# PowerShell
$env:PATH -split ';' | Select-String Python

# Add to PATH if missing
$env:PATH += ";$env:APPDATA\Python\Python3X\Scripts"

Use py launcher:
```
py -m basic_agent_chat_loop.cli
```
Run as module:
```
python -m basic_agent_chat_loop.cli
```

Import and Module Errors

"No module named 'basic_agent_chat_loop'"

Symptom: Python cannot find the package

Diagnosis:

# Check what Python is being used
which python
python --version

# Check installed packages
pip list | grep basic-agent-chat-loop

# Check sys.path
python -c "import sys; print('\n'.join(sys.path))"

Solutions:

Reinstall the package:

pip install --force-reinstall basic-agent-chat-loop

Ensure using correct Python:

# Use specific Python version
python3 -m pip install basic-agent-chat-loop

Check virtual environment:

# Activate the correct venv
source venv/bin/activate
pip install basic-agent-chat-loop

"ModuleNotFoundError: No module named 'anthropic_bedrock'"

Symptom: Missing AWS Bedrock dependency

Solution:

# Install with bedrock support
pip install basic-agent-chat-loop[bedrock]

"ModuleNotFoundError: No module named 'readline'"

Symptom: Windows missing readline support

Solution:

# Install with Windows support
pip install basic-agent-chat-loop[windows]

Agent Loading Issues

Agent file not found

Symptom: Error: Agent file not found: path/to/agent.py

Solutions:

Use absolute path:
```
chat_loop /full/path/to/agent.py
```

Use relative path from current directory:

cd /directory/with/agent
chat_loop agent.py

Use alias system:

# Save as alias once
chat_loop --save-alias myagent /full/path/to/agent.py

# Use from anywhere
chat_loop myagent

Environment variables and credentials

Note: The chat loop framework does not load .env files. Environment variable handling is the responsibility of individual agents.

Solutions:

Agent-level configuration: If your agent needs environment variables, have the agent load its own .env file using python-dotenv:
```
# In your agent code
from dotenv import load_dotenv
load_dotenv()  # Loads .env from agent's directory
```
System environment variables: Set environment variables before running the chat loop:
```
export API_KEY=your_key
export SECRET=your_secret
chat_loop agent.py
```
Shell profile: Add variables to ~/.bashrc, ~/.zshrc, or equivalent for persistence

Agent import errors

Symptom: ImportError when loading agent module

Solutions:

Ensure agent dependencies are installed:
```
pip install -r requirements.txt
```

Check Python path includes agent directory:

export PYTHONPATH=/path/to/agent/directory:$PYTHONPATH

Configuration Issues

Config file not being read

Symptom: Settings in ~/.chatrc are not applied

Diagnosis:

# Check if config exists
ls -la ~/.chatrc

# Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('$HOME/.chatrc'))"

Solutions:

Recreate config file:

# Delete existing config
rm ~/.chatrc

# Package will recreate on next run
python -c "from basic_agent_chat_loop.chat_config import get_config; get_config()"

Fix YAML syntax errors:

# Ensure proper indentation (spaces, not tabs)
features:
  show_tokens: true  # Note: 2 spaces for indentation
  auto_save: false

Use explicit config path:

chat_loop agent.py --config /path/to/custom.chatrc

Colors not displaying correctly

Symptom: Terminal shows escape codes or wrong colors

Solutions:

Check terminal supports ANSI colors:
```
echo -e "\033[94mBlue Text\033[0m"
```
Use a modern terminal emulator:
- macOS: iTerm2, Terminal.app
- Linux: GNOME Terminal, Konsole
- Windows: Windows Terminal (recommended)

Disable colors if needed:

# In ~/.chatrc
features:
  rich_enabled: false

Terminal and Display Issues

Formatting issues or broken output

Symptom: Markdown not rendering, or garbled text

Solutions:

Ensure rich is installed:
```
pip install rich>=13.7.0
```

Disable rich formatting:

# In ~/.chatrc
features:
  rich_enabled: false

Update terminal:
- Windows: Use Windows Terminal instead of CMD
- macOS: Update Terminal.app or use iTerm2
- Linux: Use modern terminal with UTF-8 support

Unicode/emoji display issues

Symptom: Boxes or question marks instead of emojis

Solutions:

Ensure terminal uses UTF-8:

# Add to ~/.bashrc or ~/.zshrc
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Install fonts with emoji support:
- macOS: System fonts support emojis
- Linux: sudo apt install fonts-noto-color-emoji
- Windows: Use Windows Terminal with modern fonts

Screen not clearing properly

Symptom: clear command leaves artifacts

Solutions:

Try alternate clear method:
- Type exit and restart
- Or manually: Ctrl+L (Unix) or cls (Windows)

Check terminal capabilities:

echo $TERM
# Should show something like: xterm-256color

Command History Issues

History not persisting between sessions

Symptom: Up arrow doesn't recall previous commands

Solutions:

Check if history file exists:
```
ls -la ~/.chat_history
```

Ensure readline is enabled:

# In ~/.chatrc
features:
  readline_enabled: true

Windows: Install pyreadline3:

pip install basic-agent-chat-loop[windows]

History file permission errors

Symptom: PermissionError: [Errno 13] Permission denied: '~/.chat_history'

Solutions:

# Fix permissions
chmod 644 ~/.chat_history

# Or delete and recreate
rm ~/.chat_history

Performance Issues

Slow startup time

Solutions:

Lazy load rich library (future enhancement)
Check agent initialization time - may be agent-specific

Profile slow operations:

python -m cProfile -m basic_agent_chat_loop.cli agent.py

High memory usage

Solutions:

Limit conversation history (future feature)
Monitor agent memory usage - may be agent-specific

Use system monitoring:

# macOS/Linux
top -p $(pgrep -f chat_loop)

# Windows
tasklist | findstr python

Platform-Specific Issues

macOS: SSL Certificate Issues

Symptom: Certificate verification errors

Solution:

# Run certificate installer
/Applications/Python*/Install\ Certificates.command

Linux: Missing dependencies

Symptom: Various import errors

Solutions:

# Debian/Ubuntu
sudo apt update
sudo apt install python3-pip python3-dev

# RHEL/CentOS/Fedora
sudo dnf install python3-pip python3-devel

Windows: PowerShell Execution Policy

Symptom: Scripts blocked by execution policy

Solution:

# Set policy for current user
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows: ANSI color support

Symptom: No colors in older Windows terminals

Solutions:

Use Windows Terminal (recommended)

Enable ANSI in PowerShell:

Set-ItemProperty HKCU:\Console VirtualTerminalLevel -Type DWORD 1

Getting More Help

If you're still experiencing issues:

Check GitHub Issues: Existing Issues
Search Discussions: GitHub Discussions
File a Bug Report: New Issue

When reporting issues, please include:

Operating system and version
Python version (python --version)
Package version (pip show basic-agent-chat-loop)
Full error message and traceback
Steps to reproduce the issue

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Troubleshooting Guide

Table of Contents

Installation Issues

Package not found on PyPI

Permission denied during installation

SSL certificate errors

Dependency conflicts

Command Not Found

"chat_loop: command not found" on macOS/Linux

"chat_loop: command not found" on Windows

Import and Module Errors

"No module named 'basic_agent_chat_loop'"

"ModuleNotFoundError: No module named 'anthropic_bedrock'"

"ModuleNotFoundError: No module named 'readline'"

Agent Loading Issues

Agent file not found

Environment variables and credentials

Agent import errors

Configuration Issues

Config file not being read

Colors not displaying correctly

Terminal and Display Issues

Formatting issues or broken output

Unicode/emoji display issues

Screen not clearing properly

Command History Issues

History not persisting between sessions

History file permission errors

Performance Issues

Slow startup time

High memory usage

Platform-Specific Issues

macOS: SSL Certificate Issues

Linux: Missing dependencies

Windows: PowerShell Execution Policy

Windows: ANSI color support

Getting More Help

See Also