Troubleshooting

This page covers common issues you might encounter when installing and using Vicoa, along with their solutions.

Installation Issues

Command not found: pip

Problem: When running pip install vicoa && vicoa, you get the error:

zsh: command not found: pip

Solutions:

Option 1: Use python3 -m pip

python3 -m pip install vicoa && vicoa

Option 2: Install Python with pip

If you don't have pip installed, you need to install Python first:

On macOS:

# Using Homebrew
brew install python

# Using official installer
# Download from https://www.python.org/downloads/

On Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip

On Windows:

Download Python from python.org
Make sure to check "Add Python to PATH" during installation

Option 3: Use pip3 instead

pip3 install vicoa && vicoa

Python version compatibility error

Problem: When running pip install vicoa, you get this error:

ERROR: Ignored the following versions that require a different python version: 1.0.1 Requires-Python >=3.10; 1.0.2 Requires-Python >=3.10
ERROR: Could not find a version that satisfies the requirement vicoa (from versions: none)
ERROR: No matching distribution found for vicoa

This means your Python version is older than 3.10, which is required for Vicoa.

Solution: Check and upgrade your Python version:

Step 1: Check your current Python version

python --version
# or
python3 --version

Step 2: Upgrade Python

On macOS:

# Option 1: Using Homebrew (recommended)
brew install python@3.11

# Option 2: Using pyenv for version management
brew install pyenv
pyenv install 3.11.0
pyenv global 3.11.0

# Option 3: Download from python.org
# Visit https://www.python.org/downloads/macos/

On Ubuntu/Debian:

# Update package list
sudo apt update

# Install Python 3.11
sudo apt install python3.11 python3.11-pip

# Set as default (optional)
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1

On CentOS/RHEL/Fedora:

# For Fedora
sudo dnf install python3.11 python3.11-pip

# For CentOS/RHEL (enable EPEL first)
sudo yum install epel-release
sudo yum install python311 python311-pip

On Windows:

Go to python.org/downloads
Download Python 3.11 or later
Run the installer and check "Add Python to PATH"
Restart your command prompt

Step 3: Verify installation and install Vicoa

# Check new Python version
python3.11 --version

# Install Vicoa with the new Python version
python3.11 -m pip install vicoa

# Run Vicoa
python3.11 -m vicoa
# or just
vicoa

Alternative: Use pyenv (recommended for developers)

# Install pyenv
curl https://pyenv.run | bash

# Add to your shell profile (~/.bashrc, ~/.zshrc)
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

# Install and use Python 3.11
pyenv install 3.11.0
pyenv global 3.11.0

# Now install Vicoa
pip install vicoa

Invalid requirement: '&&'

Problem: When running pip install vicoa && vicoa, you see:

ERROR: Invalid requirement: '&&'
Expected package name at the start of dependency specifier

This happens when your shell doesn't interpret && as a command separator and instead passes it to pip as part of the package list.

Solutions:

Option 1: Run the commands separately

pip install vicoa
vicoa

Option 2: Use a shell that supports `&&`

Run the original command from a POSIX-compatible shell like bash or zsh, or in newer PowerShell versions:

pip install vicoa && vicoa

If you are using the fish shell, use ; and instead:

pip install vicoa; and vicoa

ModuleNotFoundError: No module named 'maturin'

Problem: While running pip install vicoa, you see:

ModuleNotFoundError: No module named 'maturin'

This happens when pip cannot download the pre-built wheel and instead tries to compile Vicoa from source without the Rust build backend maturin. This scenario is common on minimal environments (for example A-Shell on iOS) but can occur on any system missing Rust tooling.

Solutions:

Option 1: Install maturin (works wherever you can install Python packages)

python3 -m pip install --upgrade pip
python3 -m pip install maturin
python3 -m pip install vicoa

Option 2: Ensure a wheel can be downloaded

On desktop Linux/macOS/Windows, upgrade packaging tools so pip prefers wheels:

python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install vicoa

On A-Shell or other lightweight shells, confirm internet access and retry the install after upgrading pip. If wheels are unavailable for your platform, fall back to option 3.

Option 3 (not recommended): Compile from source with Rust

Only try this if you understand the implications—building on constrained shells like A-Shell is slow, fragile, and easy to break. When possible, move to a desktop machine or another Python environment where wheels are available.

If you absolutely must proceed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
python3 -m pip install maturin
python3 -m pip install vicoa

Again, prefer avoiding this route; most users are better off switching environments rather than compiling locally.

If the error persists even after these steps, consider switching to a desktop environment or opening a support ticket—fighting the source build usually costs more time than it saves.

Connection Issues

Authorization problems

Problem: Web authorization fails or doesn't complete.

Solutions:

Clear browser cache: Clear cookies and cache for the Vicoa website
Try incognito/private mode: Use a private browser window
Disable browser extensions: Temporarily disable ad blockers and other extensions
Check popup blockers: Ensure popups are allowed for the Vicoa domain

Runtime Issues

Vicoa stops responding

Problem: The Vicoa CLI becomes unresponsive or freezes.

Solutions:

Restart Vicoa: Press Ctrl+C to stop, then run vicoa again
Check system resources: Ensure you have enough RAM and CPU available
Update Vicoa: Run pip install --upgrade vicoa

Mobile App Issues

iOS app not syncing

Problem: The iOS app doesn't show your active sessions.

Solutions:

Force refresh: Pull down on the sessions list to refresh
Check account: Ensure you're logged into the same account
Restart app: Close and reopen the Vicoa app
Check CLI connection: Verify your CLI is still connected

Getting Help

If you're still experiencing issues:

Raise issues on GitHub: https://github.com/vicoa-ai/vicoa-open/issues
Contact support at hi@habitrewards.me
Include details: When reporting issues, include:
- Your operating system and version
- Python version (python --version)
- Vicoa version (pip show vicoa)
- Full error messages
- Steps to reproduce the issue

Common Commands Reference

Here are the most commonly used commands for troubleshooting:

# Check Python version
python --version
python3 --version

# Check pip version
pip --version
pip3 --version

# Check Vicoa installation
pip show vicoa

# Upgrade Vicoa
pip install --upgrade vicoa

# Install with user permissions
pip install --user vicoa

# Install in virtual environment
python3 -m venv vicoa-env
source vicoa-env/bin/activate
pip install vicoa

On this page