Debug Streamlit frontend and backend changes using make debug with hot-reload. Use when testing code changes, investigating bugs, checking UI behavior, or needing screenshots of the running app.
npxskills add streamlit/streamlit--skill debugging-streamlitLoading…
make debug my_app.py
This starts both backend (Streamlit/Python) and frontend (Vite/React) with hot-reload. The app URL is printed on startup (default http://localhost:3001; 3000 is reserved for manual make frontend-dev; it may use 3002+ if other debug sessions are running). Avoid pinning VITE_PORT unless you have a specific hard requirement (last resort).
Hot-reload behavior:
frontend/ code are applied within seconds.lib/streamlit/) require restarting .make debugEach make debug run writes logs to a per-session directory under work-tmp/debug/ and updates work-tmp/debug/latest/ to point at the most recent session.
Because latest/* is a symlink, it can move if multiple debug sessions are starting/stopping concurrently—prefer using the session directory path printed by make debug when you need stable log references.
You can find the exact session directory in the make debug startup output under the Log files section.
| File | Content |
|---|---|
work-tmp/debug/latest/backend.log | Python print() statements, Streamlit logs, errors |
work-tmp/debug/latest/frontend.log | Browser console.log(), React errors, Vite output |
Logs are cleared at the start of each session and persist after exit for post-mortem analysis.
Log size warning: Logs can grow large during extended debugging sessions. Instead of reading entire log files, use rg to search for specific patterns:
# Search for specific debug messages
rg "DEBUG:" work-tmp/debug/latest/backend.log
# Search for errors (case-insensitive)
rg -i "error|exception|traceback" work-tmp/debug/latest/backend.log
# Search with context (3 lines before/after)
rg -C 3 "my_function" work-tmp/debug/latest/backend.log
# Search frontend logs for specific component
rg "MyComponent" work-tmp/debug/latest/frontend.log
Use this directory for all debugging artifacts (scripts, screenshots, etc.) to keep them organized.
Backend (Python):
print(f"DEBUG: session_state = {st.session_state}")
Frontend (TypeScript/React):
console.log("DEBUG: props =", props)
Frontend console.log() output appears in work-tmp/debug/latest/frontend.log (or the current session's frontend.log file).
work-tmp/debug/ (e.g., work-tmp/debug/test_feature.py)make debug work-tmp/debug/test_feature.pywork-tmp/debug/latest/backend.log for Error/Exception and work-tmp/debug/latest/frontend.log for console errors to ensure both servers started correctlyhttp://localhost:3001, but it may be 3002+)work-tmp/debug/latest/backend.log again for any errors after the first app accesswork-tmp/debug/latest/backend.log and work-tmp/debug/latest/frontend.logQuick error check:
# Backend errors
rg -i "error|exception" work-tmp/debug/latest/backend.log
# Frontend console errors
rg -i "error" work-tmp/debug/latest/frontend.log
For advanced debugging with screenshots or automated UI interaction.
For simple screenshots and interactions, use @playwright/cli (available in frontend devDependencies):
cd frontend
STREAMLIT_APP_URL=http://localhost:3001
yarn playwright-cli open "$STREAMLIT_APP_URL"
yarn playwright-cli screenshot --filename ../work-tmp/debug/screenshot.png --full-page
yarn playwright-cli close
See https://github.com/microsoft/playwright-cli for more commands (snapshot, click, fill, etc.).
For complex interactions, create temporary Playwright scripts in work-tmp/debug/:
# work-tmp/debug/debug_screenshot.py
"""Temporary Playwright script for debugging - run against make debug."""
import os
from playwright.sync_api import sync_playwright, expect
from e2e_playwright.shared.app_utils import get_text_input, click_button
from e2e_playwright.conftest import wait_for_app_loaded, wait_for_app_run
def main():
app_url = os.environ.get("STREAMLIT_APP_URL", "http://localhost:3001")
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
page = browser.new_page(viewport={"width": 1280, "height": 720})
# Connect to app started with `make debug`
page.goto(app_url)
wait_for_app_loaded(page)
# Interact with the app
text_input = get_text_input(page, "Name")
text_input.fill("Test User")
click_button(page, "Submit")
wait_for_app_run(page)
# Verify and screenshot
expect(page.get_by_text("Hello, Test User")).to_be_visible()
page.screenshot(path="work-tmp/debug/debug_screenshot.png", full_page=True)
print("Screenshot saved to work-tmp/debug/debug_screenshot.png")
browser.close()
if __name__ == "__main__":
main()
Ensure make debug <app.py> is running first (start it in a background task if needed). If your make debug session is using a non-default port, set STREAMLIT_APP_URL accordingly, then run the Playwright script:
STREAMLIT_APP_URL=http://localhost:3001 \
PYTHONPATH=. uv run python work-tmp/debug/debug_screenshot.py
This uses the uv-managed environment with all dependencies (playwright, etc.) and makes e2e_playwright importable without path manipulation.
Element Locators & Interactions (e2e_playwright.shared.app_utils):
Provides helpers like get_text_input(), get_button(), click_button(), get_checkbox(), etc.
Synchronization (e2e_playwright.conftest):
wait_for_app_loaded(page) - wait for initial loadwait_for_app_run(page) - wait for script execution after interactionwait_until(page, fn, timeout) - poll until condition is truePlaywright API Reference: https://playwright.dev/python/docs/api/class-playwright
# Full page screenshot
page.screenshot(path="work-tmp/debug/full.png", full_page=True)
# Element screenshot
element = page.get_by_test_id("stDataFrame")
element.screenshot(path="work-tmp/debug/dataframe.png")
Port already in use / multiple sessions:
make debug will automatically pick a free frontend port (typically in the 3001-3100 range) so multiple debug sessions can run simultaneously.3000 is reserved for manual make frontend-dev sessions.VITE_PORT=3002 make debug <app.py> (last resort).Hot-reload not working:
lib/streamlit/ require restarting make debug.work-tmp/debug/latest/frontend.log for Vite errors. TypeScript errors can break HMR.Playwright script fails to connect:
make debug is running and healthywait_for_app_loaded(page) is called after page.goto()After debugging is complete, remove temporary scripts and screenshots from work-tmp/debug/.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).