Common Errors & Solutions

Common Errors & Solutions

This guide covers the top 20 errors encountered when using Seed & Source templates. Each error includes the exact error message, root cause, and step-by-step solution.

Quick Navigation:

• CLI Errors (1-3)
• Docker Errors (4-6)
• Injection Errors (7-9)
• Webhook Errors (10-12)
• Database Errors (13-14)
• Environment Configuration Errors (15-16)
• Dependency Errors (17-18)
• Build Errors (19-20)
• Getting More Help

---

CLI Errors

Error 1: “sscli: command not found”

Error Message:

zsh: command not found: sscli

Cause: CLI not installed or not in PATH

Solution:

# Install via pip
pip install sscli

# Verify installation
sscli --version

# If still not found, check PATH
echo $PATH | grep -o "[^:]*python[^:]*"

# Add to PATH (if needed)
export PATH="$PATH:$HOME/.local/bin"

# For permanent fix, add to ~/.zshrc or ~/.bashrc
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc
source ~/.zshrc

Alternative Causes:

• Wrong Python environment: If using virtual environments, ensure venv is activated
• Permission issues: Try pip install --user sscli
• Multiple Python versions: Use python3 -m pip install sscli

---

Error 2: “License verification failed”

Error Message:

Error: License verification failed: Invalid license key

Cause: License key not configured or invalid

Solution:

# Check if license configured
cat ~/.config/sscli/config.json

# Add license key
sscli auth login YOUR_LICENSE_KEY

# Verify
sscli whoami

# Should display:
# User: your-email@example.com
# Tier: PRO/ALPHA
# Status: ACTIVE

Common Issues:

• Using FREE tier: Some templates require PRO/ALPHA tier
• Expired license: Check expiration date with sscli whoami
• Typo in key: License keys are case-sensitive
• Offline verification: Ensure internet connection for license server

---

Error 3: “Template not found”

Error Message:

Error: Template 'python-saas' not found

Real Error from Code:

Error: Base template not found: python-saas

Cause: Template name typo or not available for your license tier

Solution:

# List available templates
sscli explore

# Check exact template names:
# - python-saas
# - react-client
# - rails-api
# - rails-ui-kit
# - static-landing
# - data-pipeline

# Use exact name from list
sscli new --template python-saas --name my-project

# Check license tier includes template
sscli whoami

Additional Troubleshooting:

/path/to/foundry-meta

# For internal development, check FOUNDRY_ROOT
echo $FOUNDRY_ROOT

# If not set:
export FOUNDRY_ROOT="/Users/yourname/Documents/GitHub/stack-foundry/foundry-meta"

---

Docker Errors

Error 4: Docker build fails with “Cannot connect to Docker daemon”

Error Message:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock
Is the docker daemon running?

Cause: Docker not running or not installed

Solution:

# macOS: Open Docker Desktop
open -a Docker

# Wait for Docker Desktop to fully start (check whale icon in menu bar)

# Linux: Start Docker service
sudo systemctl start docker

# Enable Docker to start on boot (Linux)
sudo systemctl enable docker

# Verify Docker is running
docker ps

# Check Docker version
docker --version

Additional Checks:

# Check if Docker daemon is listening
docker info

# If permission denied on Linux:
sudo usermod -aG docker $USER
newgrp docker  # Or logout/login

---

Error 5: “Port 8000 already in use”

Error Message:

Error: Bind for 0.0.0.0:8000 failed: port is already allocated

Cause: Another process using port 8000 (common ports: 8000, 3000, 5432)

Solution:

# Find process using port
lsof -i :8000

# Output example:
# COMMAND   PID    USER   FD  TYPE  DEVICE  SIZE/OFF  NODE  NAME
# python   1234   user   3u  IPv4  0x123456  0t0  TCP *:8000 (LISTEN)

# Kill process
kill -9 1234

# Or change port in docker-compose.yml
ports:
  - "8001:8000"  # Use 8001 externally, 8000 inside container

For Multiple Services:

# Check all ports used by your stack
lsof -i :8000  # Backend
lsof -i :3000  # Frontend
lsof -i :5432  # PostgreSQL

# Kill all Docker containers
docker-compose down

# Start fresh
docker-compose up -d

---

Error 6: Docker build fails with “No space left on device”

Error Message:

Error: failed to copy files: write /var/lib/docker/...: no space left on device

Cause: Docker consuming too much disk space

Solution:

# Check Docker disk usage
docker system df

# Output example:
# TYPE           TOTAL     ACTIVE    SIZE      RECLAIMABLE
# Images         15        5         4.2GB     2.8GB (66%)
# Containers     10        2         1.1GB     900MB (81%)
# Local Volumes  5         1         500MB     400MB (80%)

# Remove unused containers/images/volumes
docker system prune -a

# WARNING: This will remove:
# - All stopped containers
# - All networks not used by at least one container
# - All images without at least one container associated to them
# - All build cache

# More targeted cleanup:
docker container prune  # Remove stopped containers only
docker image prune -a   # Remove unused images
docker volume prune     # Remove unused volumes

# Check available disk space
df -h

---

Injection Errors

Error 7: “AST parsing failed: Invalid Python syntax”

Error Message:

Error: AST parsing failed: invalid syntax (routes.py, line 42)

Cause: Target file has syntax errors before injection

Solution:

# Validate Python syntax
python -m py_compile src/ui/routes/api.py

# If errors found, common issues:
# - Missing colons after def/if/for/class
# - Unclosed brackets/parentheses/quotes
# - Wrong indentation (mixing tabs and spaces)
# - Invalid escape sequences in strings

# Check for common mistakes
python -m flake8 src/ui/routes/api.py

# Fix syntax errors first, then retry injection
sscli inject --feature commerce

Using AST Injection (Experimental):

# Enable AST-based injection
sscli new --template python-saas --name test --with-commerce --use-ast-injection

# This bypasses string markers and modifies AST directly
# More robust but experimental

---

Error 8: “Injection target not found”

Error Message:

Warning: No injection point found for COMMERCE_ROUTES in routes.py

Real Error from Code:

Error: No .sscli-metadata.json found. Project may not be generated with sscli.

Cause:

1. Template version mismatch
2. File structure manually modified
3. Missing injection markers
4. Not in a sscli-generated project

Solution:

# Check if project generated with sscli
cat .sscli-metadata.json

# If missing, project not generated with sscli
# You'll need manual injection

# Check template version
sscli --version

# Verify file structure matches template
ls -la src/ui/routes/

# Search for injection markers
grep -r "# SSCLI:" src/

# If markers missing, see manual injection guide:
# docs/implementation/manual_injection_guide.md

Manual Fallback:

# In src/ui/routes/api.py, add manually:
from myapp.features.commerce import commerce_router

# In route registration section:
app.include_router(commerce_router, prefix="/api/commerce")

---

Error 9: “Feature already injected”

Error Message:

Error: Commerce feature already injected. Use --force to re-inject.

Cause: Feature code already present in target files (detected via metadata)

Solution:

# Check if really injected
grep -r "commerce_router" src/

# Verify in metadata
cat .sscli-metadata.json | jq '.features_injected'

# Force re-inject (overwrites existing code)
sscli inject --feature commerce --force

# WARNING: This will overwrite manual changes

# Or manually remove old code first
git diff src/ui/routes/api.py
git restore src/ui/routes/api.py  # Undo changes
sscli inject --feature commerce

Best Practice:

• Always commit before injection: git commit -am "Before commerce injection"
• Review changes: git diff
• If mistakes, rollback: git restore .

---

Webhook Errors

Error 10: “Webhook signature validation failed”

Error Message (in server logs):

Error: Invalid webhook signature
HMAC verification failed

Cause: Webhook secret doesn’t match or request body was modified

Solution:

# Check secret matches PactaPay dashboard
echo $PACTAPAY_WEBHOOK_SECRET

# Verify in .env file
cat .env | grep WEBHOOK_SECRET

# Should match exactly (case-sensitive, no extra spaces)
PACTAPAY_WEBHOOK_SECRET=whsec_abc123...

# Test webhook signature validation
curl -X POST http://localhost:8000/webhooks/pactapay \
  -H "Content-Type: application/json" \
  -H "X-PactaPay-Signature: t=1234567890,v1=abc123..." \
  -d '{"type":"payment.succeeded","data":{}}'

Debug Signature Issues:

# In your webhook handler, add logging:
import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    print(f"Expected: {expected}")
    print(f"Received: {signature}")

    return hmac.compare_digest(expected, signature)

Common Mistakes:

• Wrong secret: Copy-paste from PactaPay dashboard
• Body modified: Raw body must be used for HMAC
• Encoding issues: Use UTF-8 encoding
• Framework middleware: Some frameworks parse body early

---

Error 11: “Webhook timeout: No response from server”

Error Message (from PactaPay dashboard):

Delivery failed: Timeout after 10 seconds
No response received from endpoint

Cause: Local server not responding, crashed, or slow processing

Solution:

# Check if server running
curl http://localhost:8000/health

# Should return: {"status":"healthy"}

# Check server logs
tail -f logs/app.log

# Or Docker logs:
docker logs -f seedsource-marketing-backend

# Common causes of timeouts:
# 1. Server crashed - restart it
# 2. Long processing in webhook handler (> 5 seconds)
# 3. Blocking I/O operations
# 4. Database connection issues

Fix Long-Running Webhooks:

# ❌ Bad: Synchronous processing (timeout risk)
@app.post("/webhooks/pactapay")
async def handle_webhook(request: Request):
    data = await request.json()
    send_email(data['customer_email'])  # Blocks for 5+ seconds
    return {"status": "ok"}

# ✅ Good: Background task
from fastapi import BackgroundTasks

@app.post("/webhooks/pactapay")
async def handle_webhook(request: Request, background_tasks: BackgroundTasks):
    data = await request.json()
    background_tasks.add_task(send_email, data['customer_email'])
    return {"status": "ok"}  # Respond immediately

Best Practice:

• Respond within 3 seconds (PactaPay timeout: 10s)
• Use background tasks for email/notifications
• Queue heavy processing (Celery, Redis Queue)
• Always return 200 OK for valid webhooks

---

Error 12: “ngrok tunnel closed unexpectedly”

Error Message:

ERR_NGROK_108: ngrok gateway error
Tunnel closed unexpectedly

Cause: Free plan tunnel auto-closed after 2 hours or connection lost

Solution:

# Restart tunnel
pkill ngrok
ngrok http 8000

# Output:
# Forwarding  https://abc123.ngrok.io -> http://localhost:8000

# Update webhook URL in PactaPay dashboard
# Old: https://xyz789.ngrok.io/webhooks/pactapay
# New: https://abc123.ngrok.io/webhooks/pactapay

# Test new URL
curl https://abc123.ngrok.io/health

Alternatives to ngrok Free:

# 1. ngrok Paid Plan ($8/month)
# - Fixed domain (no URL changes)
# - No 2-hour limit
ngrok http 8000 --subdomain=myapp

# 2. localtunnel (Free, open-source)
npm install -g localtunnel
lt --port 8000 --subdomain myapp
# URL: https://myapp.loca.lt

# 3. serveo (Free SSH tunnel)
ssh -R 80:localhost:8000 serveo.net
# URL provided in output

# 4. Tunnelmole (Free, no account required)
curl -O https://install.tunnelmole.com/install.sh
bash install.sh
tmole 8000

Production Setup:

# Don't use ngrok in production!
# Deploy to real server with fixed domain:
# - Railway.app (easiest)
# - Fly.io
# - AWS/GCP/Azure
# - Your own VPS

---

Database Errors

Error 13: “Database connection failed”

Error Message:

psycopg2.OperationalError: could not connect to server: Connection refused
Is the server running on host "localhost" (127.0.0.1) and accepting TCP/IP connections on port 5432?

Cause: PostgreSQL not running or wrong connection string

Solution:

# Check if PostgreSQL running (Docker)
docker ps | grep postgres

# If not running, start database
docker-compose up -d db

# Check connection string
echo $DATABASE_URL

# Should be: postgresql://user:pass@localhost:5432/dbname
# For Docker: postgresql://postgres:password@db:5432/myapp

# Test connection
psql $DATABASE_URL -c "SELECT 1"

# Or using Python:
python -c "from sqlalchemy import create_engine; engine = create_engine('$DATABASE_URL'); print(engine.connect())"

Common Connection String Issues:

# ❌ Wrong host (inside Docker container)
DATABASE_URL=postgresql://user:pass@localhost:5432/db  # Wrong

# ✅ Correct host (use service name from docker-compose.yml)
DATABASE_URL=postgresql://user:pass@db:5432/db

# ❌ Wrong port
DATABASE_URL=postgresql://user:pass@db:3306/db  # That's MySQL port

# ✅ Correct port
DATABASE_URL=postgresql://user:pass@db:5432/db

---

Error 14: “Migration failed: Table already exists”

Error Message:

alembic.util.exc.CommandError: Table 'users' already exists
sqlalchemy.exc.ProgrammingError: (psycopg2.errors.DuplicateTable)

Cause: Database not clean or migrations out of sync

Solution (Development Only):

# ⚠️  WARNING: This deletes ALL data!

# Stop containers
docker-compose down

# Remove volumes (includes database data)
docker-compose down -v

# Start fresh
docker-compose up -d db

# Wait for database to be ready
sleep 5

# Run migrations
alembic upgrade head

# Or for Django:
python manage.py migrate

# Or for Rails:
rails db:migrate

Manual Database Reset:

# Connect to database
psql $DATABASE_URL

# Drop all tables
DROP SCHEMA public CASCADE;
CREATE SCHEMA public;

# Grant permissions
GRANT ALL ON SCHEMA public TO postgres;
GRANT ALL ON SCHEMA public TO public;

# Exit psql
\q

# Re-run migrations
alembic upgrade head

Production Approach:

# Never drop production database!
# Instead, create new migration to fix conflicts:

alembic revision -m "fix_duplicate_table"

# In migration file:
def upgrade():
    # Check if table exists before creating
    from sqlalchemy import inspect
    conn = op.get_bind()
    inspector = inspect(conn)

    if 'users' not in inspector.get_table_names():
        op.create_table('users', ...)

---

Environment Configuration Errors

Error 15: “Environment variable not set”

Error Message:

KeyError: 'JWT_SECRET'
Error: Required environment variable 'JWT_SECRET' is not set

Cause: .env file missing or not loaded

Solution:

# Check .env exists
ls -la .env

# If missing, copy from example
cp .env.example .env

# Edit required variables
vim .env

# Or using sed:
sed -i '' 's/JWT_SECRET=.*/JWT_SECRET='$(openssl rand -base64 32)'/' .env

# Verify loaded (in Python app)
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.getenv('JWT_SECRET'))"

# For Docker, restart to load new env vars
docker-compose restart backend

Common Issues:

# ❌ .env not loaded
# Solution: Install python-dotenv
pip install python-dotenv

# In main.py:
from dotenv import load_dotenv
load_dotenv()

# ❌ .env in wrong directory
# Check current directory:
pwd

# .env should be in project root, not subdirectory
ls -la .env  # Should exist at root

---

Error 16: “Invalid JWT_SECRET length”

Error Message:

ValueError: JWT_SECRET must be at least 32 characters

Cause: Weak secret in .env file (security validation)

Solution:

# Generate SECURE secret (32+ bytes)
openssl rand -base64 32

# Output example:
# a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

# Update .env file
echo "JWT_SECRET=$(openssl rand -base64 32)" >> .env

# Or manually edit:
vim .env
# JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

# Restart server
docker-compose restart backend

Security Best Practices:

# ❌ Weak secrets (NEVER use these)
JWT_SECRET=secret123
JWT_SECRET=password

# ✅ Strong secrets (cryptographically random)
JWT_SECRET=$(openssl rand -base64 32)
JWT_SECRET=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')

# Never commit .env to git
echo ".env" >> .gitignore

---

Dependency Errors

Error 17: “ModuleNotFoundError: No module named ‘fastapi’”

Error Message:

ModuleNotFoundError: No module named 'fastapi'
ImportError: cannot import name 'FastAPI' from 'fastapi'

Cause: Dependencies not installed or wrong Python environment

Solution:

/path/to/venv/bin/python

# Check if in virtual environment
which python

# If not, activate venv:
source venv/bin/activate  # Linux/macOS
# Or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Or with Poetry:
poetry install

# Verify installation
python -c "import fastapi; print(fastapi.__version__)"

# If still fails, try upgrading pip
pip install --upgrade pip
pip install -r requirements.txt

Docker Environment:

# If error occurs in Docker container
docker-compose build --no-cache backend
docker-compose up -d backend

# Check if requirements.txt is copied to container
docker-compose exec backend ls -la requirements.txt

# Manually install inside container (temporary fix)
docker-compose exec backend pip install fastapi

---

Error 18: “CORS error: Origin not allowed”

Error Message (Browser console):

Access to fetch at 'http://localhost:8000/api/users' from origin 'http://localhost:3000'
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present.

Cause: CORS not configured to allow React client origin

Solution:

# In src/main.py (FastAPI)
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:3000",  # React dev server
        "http://localhost:5173",  # Vite dev server
    ],
    allow_credentials=True,
    allow_methods=["*"],  # Allow all methods (GET, POST, PUT, DELETE, etc.)
    allow_headers=["*"],  # Allow all headers
)

Production Setup:

# Use environment variable for flexibility
import os

ALLOWED_ORIGINS = os.getenv("ALLOWED_ORIGINS", "http://localhost:3000").split(",")

app.add_middleware(
    CORSMiddleware,
    allow_origins=ALLOWED_ORIGINS,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

In .env:

# Development
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# Production
ALLOWED_ORIGINS=https://myapp.com,https://www.myapp.com

---

Build Errors

Error 19: “npm ERR! code ELIFECYCLE”

Error Message:

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! react-client@1.0.0 build: `tsc && vite build`
npm ERR! Exit status 1

Cause: Generic npm build failure - check logs for actual error

Solution:

# Clear npm cache
npm cache clean --force

# Remove node_modules and lock file
rm -rf node_modules package-lock.json

# Reinstall dependencies
npm install

# Try build again
npm run build

# Check for specific errors in output:
# - TypeScript errors: Fix type issues
# - ESLint errors: Fix linting issues
# - Missing dependencies: npm install <package>

# Common specific errors:
# "Cannot find module '@types/react'"
npm install --save-dev @types/react @types/react-dom

# "Property 'xxx' does not exist on type 'yyy'"
# Fix TypeScript types in code

TypeScript Build Errors:

# Run TypeScript check separately
npx tsc --noEmit

# This shows all type errors without building
# Fix each error, then rebuild

---

Error 20: “Docker build fails: Dockerfile syntax error”

Error Message:

Error parsing Dockerfile: Syntax error - can't find = in "RUN"
failed to solve with frontend dockerfile.v0

Cause: Invalid Dockerfile syntax

Common Mistakes:

# ❌ Wrong: Backslash at end of line without proper continuation
RUN pip install -r requirements.txt \
&&  apt-get update

# ✅ Correct: Consistent indentation after continuation
RUN pip install -r requirements.txt && \
    apt-get update && \
    apt-get install -y postgresql-client

# ❌ Wrong: Space before continuation character
RUN echo "hello" \
    echo "world"

# ✅ Correct: No space before backslash
RUN echo "hello" \
    echo "world"

# ❌ Wrong: Missing quotes in COPY
COPY requirements.txt /app

# ✅ Correct (if filename has spaces)
COPY "requirements with spaces.txt" /app/

# ❌ Wrong: ENV without value
ENV NODE_ENV

# ✅ Correct
ENV NODE_ENV=production

Validate Dockerfile:

# Build without cache to catch all errors
docker build --no-cache -t test .

# Use hadolint (Dockerfile linter)
brew install hadolint  # macOS
hadolint Dockerfile

# Output shows best practices and errors

---

Getting More Help

If you encounter an error not listed here:

1. Search Documentation

• Injection Issues - Feature injection specific errors
• Webhook Failures - Webhook debugging
• Diagnostic Commands - Quick health checks

2. Run Diagnostics

# System check
sscli --version
docker --version
python --version

# License check
sscli whoami

# Project check
cat .sscli-metadata.json

3. Check Logs

# Docker logs
docker-compose logs -f

# Specific service
docker logs seedsource-marketing-backend

# Real-time monitoring
docker-compose logs -f --tail=100 backend

4. GitHub Issues

Search existing issues: https://github.com/seed-source/stack-cli/issues

When creating new issue, include:

• Error message (full output)
• sscli version: sscli --version
• Operating system: macOS 13.4, Ubuntu 22.04, etc.
• Python version: python --version
• Docker version: docker --version
• Steps to reproduce
• Expected behavior
• Actual behavior

5. Contact Support

Email: support@seedsource.dev

Include:

• Error details (as above)
• Output of: sscli whoami
• Output of: docker-compose config
• Relevant logs

---

Quick Diagnostic Checklist

Before reporting an error, try:

1. ✅ Update CLI: pip install --upgrade sscli
2. ✅ Restart Docker: docker-compose down && docker-compose up -d
3. ✅ Check logs: docker-compose logs --tail=50
4. ✅ Verify license: sscli whoami
5. ✅ Check .env: cat .env (ensure all vars set)
6. ✅ Clean build: docker-compose build --no-cache
7. ✅ Check syntax: python -m py_compile src/**/*.py
8. ✅ Verify ports: lsof -i :8000 -i :3000 -i :5432

---

Last Updated: February 28, 2026 Version: 1.0 Maintainer: Seed & Source Team