Troubleshooting
Troubleshooting Guide
While Peeps AI is designed to provide a seamless experience, you may encounter issues during setup, configuration, or execution. This troubleshooting guide addresses common challenges and provides step-by-step solutions to help you resolve them efficiently.
❖ Installation Problems
Issue: Dependency installation fails during the setup.
Possible Causes and Solutions:
❖ Python Version Mismatch Peeps AI requires Python >=3.10 and <3.13.
Check your Python version:
python --version
If the version is incorrect, download the correct version from Python.org and ensure it is properly added to your PATH.
❖ Outdated pip
Upgrade
pip
to the latest version:python -m pip install --upgrade pip
❖ Missing Build Tools Some dependencies require additional tools:
On Windows: Install Visual C++ Build Tools.
On Linux: Install
build-essential
:sudo apt-get install build-essential
On macOS: Install Xcode Command Line Tools:
xcode-select --install
❖ Virtual Environment Errors
Issue: Virtual environment commands fail or dependencies aren’t isolated.
Solutions:
❖ Ensure the virtual environment is activated:
On Unix/macOS:
source venv/bin/activate
On Windows:
venv\Scripts\activate
❖ If activation fails, recreate the virtual environment:
python -m venv venv
❖ If dependencies conflict, clear the environment and reinstall:
rm -rf venv
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
❖ YAML Configuration Issues
Issue: Errors when loading agents.yaml
or tasks.yaml
.
Possible Causes and Solutions:
❖ Syntax Errors YAML is sensitive to indentation.
Use a linter or online YAML validator to check for formatting issues.
Ensure consistent use of spaces (no tabs).
❖ Undefined Agents or Tasks
Ensure all tasks reference valid agents defined in
agents.yaml
.Example:
# tasks.yaml
research_task:
description: "Perform analysis"
agent: researcher
# agents.yaml
researcher:
role: "Researcher"
goal: "Analyze trends"
❖ Dynamic Input Errors
For tasks with placeholders like {sector}
, ensure you pass the required input during execution.
❖ Execution Errors
Issue: The project fails to run or outputs unexpected results.
Possible Causes and Solutions:
❖ Missing Dependencies
Verify that all dependencies are installed:
pip install -r requirements.txt
❖ Environment Variables Not Set
Ensure the
.env
file contains required keys (e.g.,OPENAI_API_KEY
).Example
.env
:OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
❖ Task Misconfiguration
Check
tasks.yaml
for valid descriptions, outputs, and assigned agents.
❖ Agent Behavior Issues
Test agent definitions in
agents.yaml
:from peepsai import load_agents agents = load_agents("config/agents.yaml") print(agents)
❖ Command Line Interface (CLI) Issues
Issue: Commands like peepsai run
fail.
Solutions:
❖ Ensure the Project Directory is Correct Navigate to your Peeps AI project directory:
cd ~/projects/my_project
❖ Verify the Peeps AI Installation Confirm that Peeps AI is correctly installed by running:
python -m peepsai --version
If this command fails, it may indicate an issue with your project setup.
❖ Reinstall Peeps AI If the CLI remains unresponsive, re-clone the Peeps AI repository to ensure all files are correctly downloaded and installed:
# Remove the current installation
rm -rf ~/projects/peepsai
# Re-clone the Peeps AI repository
git clone https://github.com/peepsai/peepsai.git ~/projects/peepsai
cd ~/projects/peepsai
# Reinstall dependencies
python -m pip install -r requirements.txt
By ensuring the repository is properly cloned and dependencies are installed, CLI commands like peepsai run
should function as expected.
❖ Logging and Debugging
Issue: Unclear error messages or unexpected behaviors.
Solutions:
❖ Enable Verbose Mode
Add verbose=True
to your Peeps AI workflow definitions (e.g., in group.py
):
Peeps(agents=agents, tasks=tasks, process=Process.sequential, verbose=True)
❖ Check Logs Use logs to pinpoint issues:
peepsai run --log-level DEBUG
❖ Print Intermediate Outputs
Insert print statements in main.py
or group.py
to debug configurations.
❖ Git-Related Issues
Issue: Unable to clone the Peeps AI repository.
Solutions:
❖ Verify Git installation:
git --version
If not installed, download it from Git-SCM.
❖ Check internet connectivity or firewall restrictions.
❖ If cloning fails due to permissions, ensure the repository URL is correct:
git clone https://github.com/peepsai/peepsai.git
❖ Performance Issues
Issue: Tasks take too long to execute or fail to complete.
Solutions:
❖ Optimize agent definitions to reduce complexity.
❖ Use smaller datasets or limit the scope of initial tasks for testing.
❖ If using an external API (e.g., OpenAI), ensure you are within rate limits.
❖ Frequently Encountered Errors

Getting Additional Support
If you’ve tried the above solutions and still face challenges:
Visit the Peeps AI GitHub Issues Page to report bugs or view existing resolutions.
Join the Peeps AI community forums or Slack for peer assistance.
Reach out to the support team (details in the documentation).
Last updated