azure-swa-gotchas

Azure Static Web Apps Gotchas

Time saved: 2-4 hours per issue

---

The Problem

Azure Static Web Apps is powerful but has numerous edge cases that cause silent failures or confusing behavior. The documentation covers the happy path; these are the unhappy paths.

Why This Is Hard to Find

• Each gotcha is documented somewhere, but scattered across GitHub issues, Stack Overflow, and blog posts
• Error messages often don't indicate the root cause
• Some behaviors are undocumented "features"
• The combination of SWA + Functions + Auth creates emergent failure modes

---

The Gotchas

1. Auth Route Ordering Matters

Symptom: Login callbacks return 401 → infinite redirect loop

Cause: /.auth/* routes must be explicitly allowed for anonymous BEFORE any /* wildcard with authenticated.

Solution:

{
  "routes": [
    { "route": "/.auth/*", "allowedRoles": ["anonymous"] },
    { "route": "/*", "allowedRoles": ["authenticated"] }
  ]
}

Time saved: 1-2 hours

---

2. Embedded API Overrides Linked Backend

Symptom: Your linked Function App returns 404, but embedded Functions work

Cause: If the workflow has api_location:, SWA deploys embedded Functions which override any linked backend.

Solution: Remove api_location from workflow to route to the linked Function App.

# Remove this line:
# api_location: "api"

Time saved: 1-2 hours

---

3. SWA CLI v2.0.8 Silently Fails

Symptom: CLI reports success but nothing uploads

Cause: Known bug in v2.0.8

Solution: Use GitHub Actions (Azure/static-web-apps-deploy@v1) instead.

- uses: Azure/static-web-apps-deploy@v1
  with:
    azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
    repo_token: ${{ secrets.GITHUB_TOKEN }}
    action: "upload"
    app_location: "/"
    output_location: "dist"

Time saved: 30-60 min

---

4. Custom Domain Redirect URIs Required

Symptom: Auth works on default hostname, fails on custom domain