TROUBLESHOOTING STANDARDS

Flask HTML Application - Systematic Problem Solving

CRITICAL RULE: NO CODING UNTIL YOU LOCATE THE ISSUE

Never start with "ready, fire, aim" approach
Investigate thoroughly before making changes
Document your findings before proposing solutions
Ask if the problem is worth fixing vs. creating new

TROUBLESHOOTING PROCESS

STEP 1: IDENTIFY THE PROBLEM LOCATION

Given a URL showing an issue, locate all relevant files:

URL: https://domain.com/path
Route: Search in front_routes_blueprint.py for matching route
Template: Identify template from route handler (e.g., render_template('file.html'))
Static files: Check /static/html/ directory if needed

File Location Commands:
grep -n "@front.route('/path')" front_routes_blueprint.py
find . -name "*.html" | grep template_name
ls -la /var/www/html/modular.nsgia.com/static/html/

STEP 2: VERIFY FILE SYSTEM ACCESS

Check that files exist and are accessible:

Template path: /var/www/html/modular.nsgia.com/front/templates/
Static HTML path: /var/www/html/modular.nsgia.com/static/html/
File permissions: Readable by web server
File contents: Valid HTML structure

File System Checks:
ls -la /path/to/template
head -20 /path/to/file.html
file /path/to/file.html

STEP 3: DOCUMENT THE ISSUE

Clearly define what's wrong:

Expected behavior: What should happen?
Actual behavior: What is happening?
Error messages: Console, browser, or Flask logs
Issue type: Missing feature vs. broken functionality

STEP 4: ADD DEBUG OUTPUT

If no errors are visible, add debug prints to routes:

Add print statements at function start
Print variable values at each logical step
Verify template variables are passed correctly
Check file paths and existence

Debug Pattern for Routes:
print(f"DEBUG: route_name - Starting at {datetime.now()}")
print(f"DEBUG: route_name - Variable value: {variable}")
print(f"DEBUG: route_name - File path: {file_path}")
print(f"DEBUG: route_name - File exists: {os.path.exists(file_path)}")

DECISION TREE: FIX OR REPLACE?

Before Coding, Ask:

Is this adding a new feature?
- Yes → Add to existing code if it's clean
- No → Assess if it's actually broken
Is the existing code a mess?
- Yes → Create new blueprint/route
- No → Fix the specific issue
Is it complex to debug?
- Yes → Sometimes better to rewrite cleanly
- No → Fix systematically
Is it throwing errors?
- No → Add debug prints first
- Yes → Fix the error

COMMON FLASK HTML ISSUES

Template Not Found

Check template path in route handler
Verify file exists in templates directory
Check for typos in filename

Static Files Not Loading

Verify static file path in template
Check file exists in static directory
Ensure correct URL pattern: /static/path/file

Route Not Working

Check route decorator syntax
Verify blueprint is registered
Look for typos in route path

Template Variables Missing

Check if variables passed to render_template
Verify variable names match in template
Add debug prints to see variable values

INVESTIGATION CHECKLIST

Before making any changes:

□ Located the problematic route in blueprint
□ Found all associated template files
□ Verified files exist and are readable
□ Documented expected vs actual behavior
□ Added debug output if needed
□ Determined fix vs. replacement strategy
□ Identified all files that need modification

REMEMBER

Investigation time is not wasted time
Understanding the problem prevents wrong solutions
Document findings before proposing changes
Sometimes replacement is faster than fixing
Debug output helps identify exact issues
Follow the document and file prompt standards