Skip to main content
Asta includes built-in diagnostic tools to help you troubleshoot issues and verify your installation.

​
The doc Command

The doc (or doctor) command runs safe diagnostics to check your Asta installation.

​
Basic Usage

./asta.sh doc
This command checks:
  • Python version (3.12 or 3.13 required)
  • Backend virtual environment
  • Backend .env configuration
  • Workspace USER.md file
  • API health endpoint
  • Enabled skill dependencies

​
Example Output

    ╭─────────────────────────────────────────╮
    │         doc (safe diagnostics)          │
    ╰─────────────────────────────────────────╯

  ● python       ok  python3.12
  ● backend venv present
  ● backend .env present
  ● workspace user present
  ● api health   ok  /api/health
  ● skill deps   ok  all enabled skills available

  ● Doc checks passed.

​
Auto-Fix with --fix

The --fix flag attempts to automatically resolve common setup issues. 
./asta.sh doc --fix

​
What Auto-Fix Does

If the backend .venv is missing, --fix will:
  1. Find a suitable Python version (3.12 or 3.13)
  2. Create the virtual environment
  3. Install all required dependencies from requirements.txt
./asta.sh doc --fix
# Output:
# ◆ backend venv  missing  attempting auto-fix
# ● backend venv  fixed
If backend/.env is missing and .env.example exists, --fix will copy it:
./asta.sh doc --fix
# Output:
# ● backend .env  fixed  copied from .env.example
If workspace/USER.md is missing, --fix will create it with the default template:
./asta.sh doc --fix
# Output:
# ● workspace user  fixed  created workspace/USER.md
For enabled skills with missing dependencies, --fix will attempt to install them automatically:
./asta.sh doc --fix
# Output:
# ◆ skill dep    memo  install memo: brew tap antoniorodr/memo && brew install memo
# ● skill dep    fixed  memo
Some dependencies require manual installation. The diagnostic output will indicate when manual intervention is needed.

​
Checking System Status

The status command shows the current state of all Asta services and integrations. 
./asta.sh status

​
Example Status Output

  ─────────────────────────────────────────
  system status
  ─────────────────────────────────────────
  ● backend   up  pid 12345
  ─────────────────────────────────────────
  
  Server
    • API:     http://localhost:8010
    • Docs:    http://localhost:8010/docs
  
  Channels
    • Telegram: connected
  
  Skills
    • Web Search:    enabled
    • Learning (RAG): enabled
    • Spotify:       enabled
    • Reminders:     enabled
  ─────────────────────────────────────────

​
Status Information Includes

  • Backend Status: Whether the backend is running and its process ID
  • API Endpoints: URLs for the API and documentation
  • Channels: Connected external channels (Telegram, etc.)
  • Skills: Enabled skills and their availability

​
Log Files

Asta writes detailed logs that can help diagnose issues.

​
Log Locations

Backend Log

Location: backend.log (in repo root)Contains:
  • Backend startup messages
  • API request/response logs
  • Skill execution logs
  • Error tracebacks

Cloudflare Tunnel Log

Location: cloudflared.log (in repo root)Contains:
  • Tunnel connection status
  • Public URL assignments
  • Network errors

​
Viewing Logs

View the entire log: 
cat backend.log
View recent logs (last 50 lines): 
tail -50 backend.log
Follow logs in real-time: 
tail -f backend.log
Search logs for errors: 
grep -i error backend.log
grep -i exception backend.log

​
Log Rotation

Logs are automatically rotated when they exceed 5MB:
  • Current log: backend.log
  • Previous log: backend.log.old

​
Health Check Endpoint

The backend exposes a health check endpoint at /api/health. 
curl http://localhost:8010/api/health
Expected response: 
{
  "status": "ok"
}

​
Interactive API Documentation

Asta provides interactive API documentation powered by FastAPI. Access at: http://localhost:8010/docs

​
What You Can Do

  • View all available API endpoints
  • See request/response schemas
  • Test endpoints directly from the browser
  • View authentication requirements
  • Inspect model definitions

​
Common Diagnostic Workflows

  1. Run diagnostics with auto-fix:
./asta.sh doc --fix
  1. Check the backend log for errors:
tail -50 backend.log
  1. Verify Python version:
python3 --version  # Should be 3.12 or 3.13
  1. Check if port 8010 is in use:
lsof -i :8010
  1. Try a clean restart:
./asta.sh restart
  1. Check skill status:
./asta.sh status
  1. Run diagnostics to check dependencies:
./asta.sh doc
  1. Auto-fix missing dependencies:
./asta.sh doc --fix
  1. Check backend logs for skill-specific errors:
grep -i "skill_name" backend.log
  1. Verify skill is enabled in Settings → Skills
  1. Check for lock errors in logs:
grep -i "lock" backend.log
  1. Restart to release locks:
./asta.sh restart
  1. Check database file permissions:
ls -la backend/asta.db
  1. Check disk space:
df -h .
  1. If corrupt, back up and recreate:
cp backend/asta.db backend/asta.db.backup
rm backend/asta.db
./asta.sh start
  1. Check system resource usage:
top -p $(lsof -ti :8010)
  1. Check log file size:
du -h backend.log
  1. Monitor real-time logs:
tail -f backend.log
  1. Check for repeated errors:
grep -i error backend.log | sort | uniq -c | sort -rn
  1. Restart with fresh logs:
mv backend.log backend.log.archive
./asta.sh restart

​
Getting Help

If diagnostics don’t resolve your issue:
  1. Check the error reference: See Common Errors for specific error messages
  2. Review the logs: Look for ERROR or EXCEPTION messages in backend.log
  3. Verify your setup: Run ./asta.sh doc --fix to ensure proper configuration
  4. Check the API docs: Visit http://localhost:8010/docs to test endpoints
  5. Report the issue: Include relevant log excerpts when seeking help

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us