Troubleshooting Guide

Troubleshooting Guide

Audience: Developers using Seed & Source CLI (sscli) and generated templates Scope: Installation, generation, Docker, Python, React, Rails, Auth, Commerce, Deployment Updated: March 8, 2026

---

📖 Detailed Sub-Guides

For deep dives beyond this quick reference:

Guide	What it covers
Full-Stack Setup Guide	React + Rails/Python integration, CORS, auth, Docker networking
Common Errors	Error messages with exact fixes
AST Injection Issues	--use-ast-injection failures
Webhook Failures	Shopify/Stripe webhook debugging
Diagnostic Commands	Quick copy-paste diagnostic one-liners

---

Quick Reference

Fastest Diagnostic — Run This First

# Check Docker is running and healthy
docker info

# Check your sscli version
sscli --version

# Check your login status
sscli account

# Check the project's Docker services are all up
docker compose ps

# View logs for a failing service
docker compose logs <service-name> --tail 50

---

1. CLI & Installation

sscli: command not found

• Cause: sscli not installed or not on PATH.
• Fix:

  pip install sscli
  which sscli   # should return a path
  # If empty, add pip's bin to PATH:
  export PATH="$HOME/.local/bin:$PATH"   # add to ~/.zshrc

sscli login returns “Device flow failed”

• Cause: GitHub OAuth device flow timed out or network issue.
• Fix: Open the URL printed in the terminal in any browser, enter the code, complete GitHub authorization within 5 minutes. Run sscli account to confirm.

ModuleNotFoundError on sscli commands

• Fix:

  pip install --upgrade sscli
  # If using venv, activate it first then reinstall
  source venv/bin/activate && pip install sscli

sscli new fails with “License tier insufficient”

• Cause: Free tier cannot generate templates with injected features.
• Fix: sscli logout && sscli login with an ALPHA/PRO account. Verify with sscli account.

---

2. Docker & Infrastructure

Memory Issues — Container crashes with Killed or Out of memory

• Fix: Docker Desktop → Settings → Resources → increase RAM to 4GB+.

Port Conflicts — Error: Bind for 0.0.0.0:<port> failed

• Fix:

  docker ps           # see what's running
  lsof -i :<port>     # see who owns the port (macOS/Linux)

  Stop the conflicting service, or override the port in .env: APP_PORT=8001

Container never becomes healthy — shows health: starting indefinitely

• Fix:

  docker compose logs <service> --follow   # watch startup logs
  docker compose exec <service> sh         # shell in and check manually

docker compose up hangs on pulling for minutes

• Fix:

  docker pull <image>   # pull base image manually first
  docker compose build --no-cache

Volume permission denied on Linux

• Fix:

  sudo chown -R $USER:$USER .
  # or add to docker-compose.yml: user: "${UID}:${GID}"

---

3. Python Stacks (python-saas)

Pydantic ValidationError during startup

• Fix: cp .env.example .env then fill in all REQUIRED fields. Restart.

poetry.lock is not consistent with pyproject.toml

• Fix:

  poetry lock --no-update && poetry install

poetry: command not found

• Fix: pip install poetry

ImportError: No module named 'foundry_commerce' (or similar injected module)

• Fix:

  poetry install
  # or inside Docker:
  docker compose build --no-cache

Alembic migration fails — target database is not up to date

• Fix:

  alembic upgrade head
  # if conflicts: alembic history, then alembic stamp head (use carefully)

NiceGUI app starts but shows blank page

• Fix: Check console for the port. Default is http://localhost:8000. Check browser JS console for errors.

FastAPI returns 422 Unprocessable Entity

• Fix: Check the response body — it names the exact failing field. Visit /docs for interactive API docs.

---

4. React Client (react-client)

npm install fails with EACCES permission error

• Fix:

  sudo chown -R $USER ~/.npm && npm install

VITE_BACKEND_URL env var not working

• Cause: Must be prefixed with VITE_ and Vite must be restarted after .env changes.
• Fix: Stop dev server (Ctrl+C), edit .env, run npm run dev.

React app shows blank page after Docker build

• Cause: .env not baked into the Docker image (listed in .dockerignore).
• Fix:

  grep ".env" .dockerignore   # should return nothing (or only .env.local)

  Remove .env from .dockerignore and rebuild.

CORS errors — Cross-Origin Request Blocked

• Fix (python-saas backend): Add CORSMiddleware in src/infrastructure/api/app.py:

  app.add_middleware(CORSMiddleware,
      allow_origins=["http://localhost:5173"],
      allow_methods=["*"], allow_headers=["*"])

  See Full-Stack Setup Guide for details.

Admin login redirects to blank page after auth

• Fix: Check src/pages/Login.jsx — the navigate() call should route to /admin, not /dashboard.

npm run build fails — Cannot find module './components/...'

• Fix: Check injected component file names — ensure the export name matches the import path exactly.

---

5. Rails Stacks (rails-api)

PG::ConnectionBad: could not connect to server

• Fix: In docker-compose.yml, add depends_on: {postgres: {condition: service_healthy}}. Or just retry: docker compose restart rails-api.

Your Ruby version is X, but your Gemfile specified Y

• Fix: Use Docker (docker compose run rails-api bash) or switch locally: rbenv local 3.3.0.

bundle install timing out

• Fix: bundle install --retry 3

ActiveRecord::PendingMigrationError

• Fix:

  docker compose exec rails-api rails db:migrate

---

6. Static Landing (static-landing)

Astro build fails — Cannot read properties of undefined

• Cause: blueprint.json has a missing or malformed field.
• Fix: node -e "JSON.parse(require('fs').readFileSync('blueprint.json','utf8'))" — look for syntax errors.

NGINX shows 404 for all routes

• Fix: Ensure nginx.conf has: try_files $uri $uri/ /index.html;

Images not loading after Docker deploy

• Fix: Verify astro.config.mjs has public dir set correctly. Check dist/ for images after npm run build.

---

7. Feature Injection

Feature flag passed but feature not in generated project

• Fix: Check the Feature Injection Guide compatibility table. Verify license tier: sscli account.

ast-grep not found when using --use-ast-injection

• Fix:

  brew install ast-grep      # macOS
  cargo install ast-grep     # Linux/Windows with Rust

Duplicate imports after running injection twice

• Fix: Standard injection is not idempotent. Delete and regenerate, or use --use-ast-injection.

Full injection troubleshooting: AST Injection Issues

---

8. Authentication & License Server

sscli account shows “Not authenticated”

• Fix: sscli logout && sscli login

Auth token expired — 401 on API calls

• Fix: sscli login to refresh (tokens expire after 7 days).

License server unreachable (local dev mode)

• Fix:

  cd tooling/services/license-server && docker compose up
  curl http://localhost:8001/health   # should return {"status":"ok"}

---

9. Commerce & Webhooks

Shopify webhook not reaching local dev

• Fix: Use --tunnel at generation, or start ngrok manually: ngrok http 8000. Copy the public URL to Shopify Partner Dashboard.

Stripe webhook signature validation failing

• Fix: Set STRIPE_WEBHOOK_SECRET=whsec_... from Stripe Dashboard → Webhooks → your endpoint.

Full webhook troubleshooting: Webhook Failures

---

10. Payment & Injection Troubleshooting

Stripe webhook returns 400

• Cause: Expected when Stripe-Signature header is missing (e.g., direct browser request or test POST without the CLI). This is not a bug.
• Fix: Use the Stripe CLI to send test events: stripe trigger checkout.session.completed. Do not POST directly to the webhook endpoint without a valid signature.

Stripe checkout returns 502

• Cause: STRIPE_SECRET_KEY is still a placeholder (sk_test_replace_me or similar).
• Fix: Open .env, replace STRIPE_SECRET_KEY with your real key from the Stripe Dashboard → Developers → API Keys. Restart the service (docker compose restart <service>).

Import error after injection on app/ projects

• Cause: --with-payment detected an app/main.py layout but files were placed under src/ instead.
• Fix: Re-run injection with the explicit template flag:

  sscli inject --path ./my-project --features payment --template python-saas

  The injector will auto-relocate files to app/routes/payments.py and fix imports.

alembic: "Can't locate revision"

• Cause: The alembic version table references a revision ID that no longer exists in alembic/versions/.
• Fix:

  alembic stamp head      # mark current DB state as head
  alembic history         # confirm revision chain looks correct

  Use alembic stamp carefully — it does not run migrations, it only updates the version pointer.

Migration 005 not applied after deploy

• Cause: alembic upgrade head was not run after the new migration was pushed.
• Fix: From the tooling/services/license-server directory:

  alembic upgrade head

  Verify with alembic current — should show 005 (head).

---

11. Deployment (Render / Cloudflare Pages)

Render deploy fails — exit code 1 during build

• Fix: Check Render build logs (error is above the exit line). Run docker build . locally. Check for missing env vars in Render → Service → Environment.

Render health check failing

• Cause: App not responding on expected port.
• Fix: Ensure render.yaml and Dockerfile expose the same port. Add a /health route if missing.

Cloudflare Pages — “Failed to compile” for Astro project

• Fix: Cloudflare Pages settings: build command npm run build, output dir dist, Node version 18 (set NODE_VERSION=18).

VITE_* vars not visible in production React build

• Cause: Vite bakes env vars at build time — must be set before deploy.
• Fix: Set them in Render/Cloudflare, then trigger a new deploy.

---

12. “I’m Stuck” — Escalation Checklist

1. Run docker compose logs --tail 100 > /tmp/debug.log and review.
2. Run diagnostics in troubleshooting/DIAGNOSTIC_COMMANDS.md.
3. Check troubleshooting/COMMON_ERRORS.md for your exact error message.
4. Search FULL_STACK_SETUP_GUIDE.md.
5. Open an issue with: OS, sscli --version, template, flags, and full error output.

---

Last updated: March 8, 2026 — Payment & Injection Troubleshooting section added