debug-flask_skill

Overview

This skill systematically debugs Flask applications using a four-phase methodology and Flask-specific tools. It targets routing, template rendering, application/request context issues, SQLAlchemy session problems, blueprint registration, and circular imports. The goal is fast, repeatable diagnosis and safe fixes with minimal changes.

How this skill works

The skill inspects error patterns and run-time state, collects contextual logs and route maps, and guides interactive investigation via the Werkzeug debugger, Flask shell, pdb, and Flask-DebugToolbar. It prescribes targeted tests and configuration checks, then validates fixes with unit or integration tests and test-suite runs. Concrete code snippets and commands illustrate each step.

When to use it

• When you encounter 404/405 routing or endpoint mismatches
• When templates raise TemplateNotFound, UndefinedError, or syntax errors
• When you see RuntimeError about working outside application/request context
• When SQLAlchemy raises DetachedInstanceError or connection pool errors
• When blueprint registration fails or circular imports block app startup

Best practices

• Reproduce the error with a minimal test case before changing code
• Enable debug tools only in development; never run Werkzeug debugger in production
• Log request and response details and enable SQL query logging in dev
• Use flask shell and app.url_map to confirm routes and blueprint registration
• Manage SQLAlchemy sessions explicitly and close/remove sessions in teardown

Example use cases

• Fix a 404 caused by a blueprint not registered due to import ordering
• Resolve TemplateNotFound by verifying template folder configuration and blueprint template paths
• Diagnose DetachedInstanceError by inspecting session scope in tests and background tasks
• Track down 500 errors using the Werkzeug interactive traceback and in-code breakpoints
• Spot N+1 SQLAlchemy queries using query logging or Flask-DebugToolbar panels