Skip to main content
This page documents common errors you may encounter when running Asta and their solutions.
For comprehensive error documentation, see docs/ERRORS.md in the source repository.

​
Startup & Installation

Error: No .venv directory found in backend/Solution:
cd backend && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
Or use the built-in setup command:
./asta.sh setup
Error: Python dependency not installedSolution:
cd backend && source .venv/bin/activate && pip install -r requirements.txt
Error: Another process is using the backend portSolution: Restart Asta to free and restart the port:
./asta.sh restart
Alternatively, set a different port in your environment:
export ASTA_API_URL=http://localhost:8011
Error: Running commands from the wrong directorySolution: Always run asta.sh commands from the asta/ repository root directory.

​
Python Version Issues

Problem: Asta requires Python 3.12 or 3.13. Python 3.14 is not yet supported due to ChromaDB and pydantic compatibility issues.Solution: Install a compatible Python version:
# macOS
brew install [email protected]

# Then setup the backend
cd backend
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
The asta.sh script automatically prefers Python 3.12 or 3.13 and will skip 3.14+ versions.

​
API & Connection

Error: Backend is not runningSolution:
./asta.sh start
Or run uvicorn manually:
cd backend
source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8010
Error: Request origin not allowedSolution: Add your origin to ASTA_CORS_ORIGINS in backend/.env (comma-separated):
ASTA_CORS_ORIGINS=http://localhost:3000,http://localhost:5173
Restart the backend after making changes:
./asta.sh restart

​
Database & Persistence

Error: Database is locked or corruptSymptoms:
  • database is locked errors
  • ResourceWarning: Connection deleted before being closed
  • Unable to save data
Solutions:
  1. Restart Asta to release locks:
./asta.sh restart
  1. Check file permissions:
ls -la backend/asta.db
Ensure the file is writable by your user.
  1. Release stale lock holders: The asta.sh restart command automatically attempts to release stale processes holding SQLite locks.
  2. Start fresh (last resort): If the database is corrupt, back it up and remove it: 
cp backend/asta.db backend/asta.db.backup
rm backend/asta.db
./asta.sh start
Removing asta.db will delete all your conversation history, reminders, and settings. Only do this as a last resort.
Error: Workspace context file not createdSolution: Create or use the existing workspace/USER.md file:
mkdir -p workspace
cat > workspace/USER.md << 'EOF'
# About you

- **Preferred name:** 
- **Location:** 
- **Timezone:** 
- **Important:** 
  - 
EOF
Or use the doc command with auto-fix:
./asta.sh doc --fix

​
AI Providers

Error: No API key configuredSolution: Add at least one AI provider API key in Settings → API keys:
  • Groq
  • Gemini
  • Claude (Anthropic)
  • OpenAI
  • OpenRouter
  • Or run Ollama locally
# For Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama serve
Error: API key is wrong or expiredSolution:
  1. Update the key in Settings → API keys
  2. Or update backend/.env directly
  3. Restart the backend:
./asta.sh restart
Error: Ollama not running or wrong URLSolution:
  1. Start Ollama:
ollama serve
  1. If Ollama is on another host, set the correct URL in backend/.env:
OLLAMA_BASE_URL=http://your-ollama-host:11434
  1. Restart the backend:
./asta.sh restart

​
Learning / RAG

Error: RAG uses Ollama for embeddings; Ollama is not running or the model is missingSolution:
  1. Install Ollama:
curl -fsSL https://ollama.com/install.sh | sh
  1. Pull the embedding model:
ollama pull nomic-embed-text
  1. If Ollama is on another host, set OLLAMA_BASE_URL in backend/.env
  2. Refresh the Learning page in Asta
Error: ChromaDB or FTS DB could not be createdSolution:
  1. Check disk space:
df -h
  1. Check write permissions:
ls -la backend/chroma_db backend/rag_fts.db
  1. Set custom paths in backend/.env if needed:
ASTA_CHROMA_PATH=/custom/path/chroma_db
ASTA_FTS_PATH=/custom/path/rag_fts.db

​
Logs & Debugging

Backend logs location: 
# Main log file (relative to repo root)
backend.log

# Or explicitly:
./backend/backend.log
View recent logs: 
tail -f backend.log
API documentation: Access the interactive API docs when the backend is running: 
http://localhost:8010/docs

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us