# Oe Backend Startup Triage

> Debug “backend won’t start / first request 500 / ports stuck” quickly. Use when uvicorn reload behaves strangely, ports 8000/3000 are blocked, or you see first-request errors like “unexpected keyword argument” due to stale bytecode caches.

- Skill: `majiayu000/oe-backend-startup-triage` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/oe-backend-startup-triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/oe-backend-startup-triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/oe-backend-startup-triage

---


# oe-backend-startup-triage

## Preferred startup path

1. Use the canonical dev script (port cleanup + key loading):
   - `./scripts/dev/dev_server.sh start`

2. If the frontend is stuck (white page / endless spinner), clear zombie processes:
   - `kill -9 $(lsof -nP -iTCP:3000 -sTCP:LISTEN -t)`
   - `cd atelier-ai-frontend && npm run dev`

## If port 8000 is stuck

- Identify and kill listeners:
  - `lsof -nP -iTCP:8000 -sTCP:LISTEN`
  - `lsof -nP -tiTCP:8000 -sTCP:LISTEN | xargs kill -9`

## If the first request fails with “unexpected keyword argument …”

This is usually stale `.pyc` / `__pycache__` from changed dataclasses.

1. Clear bytecode caches:
   - `find backend -name "*.pyc" -delete`
   - `find backend -type d -name "__pycache__" -exec rm -rf {} +`

2. Restart with bytecode disabled:
   - `export PYTHONDONTWRITEBYTECODE=1`
   - `./scripts/dev/dev_server.sh start`

## If imports fail (ImportError / missing export)

1. Run the compile/import sanity gate:
   - `python3 scripts/tests/verify_refactor.py`

2. If the failure is in a workflow wrapper, ensure the wrapper re-exports the referenced symbol (see `docs/guides/TEAM_GUIDE.md` for prior “missing export” regressions).