I've shipped a handful of FastAPI apps this year. Every single one had me debugging the same stupid mistakes. Here are the five that cost me the most time, and the exact fixes.

1. TypeError: unhashable type: 'dict' After Upgrading Starlette

You upgrade Starlette to 1.0 and suddenly every page throws TypeError: unhashable type: 'dict'. The traceback points at Jinja2. You think it's a template problem.

It's not. Starlette 1.0 changed the TemplateResponse signature. The old 3-arg dict style is broken:

# OLD — breaks on Starlette 1.0+
return templates.TemplateResponse("page.html", {"request": request, "data": x})

# NEW — use this
return tpl.TemplateResponse(request, "page.html", {"data": x})

The old signature passes the context dict as the name parameter. Jinja2 tries to use it as a cache key. Boom.

Fix: tpl.TemplateResponse(request, template_name, context_dict). Three args, specific order. That's it.

2. Your API Data Works Locally, Breaks in Production

You fetch data from a third-party API, cache it in a JSON file, serve it in your template. Works great for 10 minutes. Then the cache expires, the external API hiccups, and your page crashes.

The mistake: except: pass.

# THIS IS HOW YOU BREAK PRODUCTION
try:
    data = await fetch(url)
except:
    pass  # silently returns None, page crashes

Fix: Always fall back to stale cache. Always log the error. Never return None when you have stale data.

async def fetch(cache_path, url, ttl=600):
    data = cached_fetch(cache_path, ttl)
    if data and not data.get('_error'):
        return data
    try:
        async with aiohttp.ClientSession() as s:
            async with s.get(url, timeout=aiohttp.ClientTimeout(total=20)) as r:
                if r.status == 200:
                    data = await r.json()
                    with open(cache_path, 'w') as f:
                        json.dump(data, f)
                    return data
    except Exception as e:
        print(f'Fetch error: {e}', file=sys.stderr)
    # Fallback: stale cache is better than no cache
    if os.path.exists(cache_path):
        try:
            with open(cache_path) as f:
                return json.load(f)
        except:
            pass
    return None

3. Nginx Returns 502 But Your Backend Logs Show 200s

Your API endpoint takes 90 seconds to respond. Backend logs show a clean 200. Browser shows 502 Bad Gateway.

Nginx default proxy_read_timeout is 60 seconds. Your backend is fine. Nginx just kills the connection before the response arrives.

Fix: Add three lines to your nginx location block:

location /api/ {
    proxy_pass http://backend:8000;
    proxy_read_timeout 120s;
    proxy_send_timeout 120s;
    proxy_connect_timeout 10s;
}

Also check: if you're using Docker hostnames in proxy_pass, nginx crashes on startup if it can't resolve them. Use variable-based resolution:

resolver 127.0.0.11 valid=10s;
set $upstream "http://backend:8000";
proxy_pass $upstream;

4. Supabase Says "Tenant or User Not Found"

You're running FastAPI on the same host as Supabase (Docker). You connect to port 5432. Supabase says "Tenant or user not found."

Port 5432 goes through supavisor, which uses tenant auth. Your app isn't a Supabase tenant.

Fix: Connect directly to the DB container's IP:

DB_IP=$(docker inspect supabase-db --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}')

conn = await asyncpg.connect(
    host=DB_IP, port=5432,
    user='supabase_admin', password='your-password',
    database='postgres'
)

Bypasses supavisor entirely. Works every time.

5. {% set %} in a Jinja2 Loop Doesn't Persist

You set a variable inside a {% for %} loop. You try to use it outside the loop. It's empty.

Jinja2 scoping is not Python scoping. Variables set inside loops don't leak out.

Fix: Do the grouping in Python before it hits the template:

groups = {}
for item in items:
    key = item['category']
    groups.setdefault(key, []).append(item)

{% for category, items in groups.items() %}
  <h2>{{ category }}</h2>
  {% for item in items %}
    <div>{{ item.name }}</div>
  {% endfor %}
{% endfor %}

I got tired of re-learning these patterns, so I packaged them into a FastAPI Web App Builder Pack — production-tested templates, deployment configs, and debugging checklists. $29, MIT licensed, use it in whatever you want.

If you just wanted the fixes, take them. That's fine too.