pal-e-docs

Review: Bug: Keycloak execute-actions-email returns 500 for new registrations

review-878-2026-04-07 Doc

review ready
Project

Verdict: READY

Round 3 re-review of board item #878. Previous reviews: NEEDS_REFINEMENT (round 1, round 2). V2 refinements verified and all [BODY] recommendations resolved.

Template Completeness

Checked against template-issue-bug required sections:
  • [x] Type -- Bug
  • [x] Lineage -- Standalone, discovered during CRM monitoring session 2026-04-07
  • [x] Repo -- forgejo_admin/basketball-api
  • [x] What Broke -- Keycloak execute-actions-email returns 500, detailed log evidence
  • [x] Repro Steps -- 4 clear steps with specific user example
  • [x] Expected Behavior -- Keycloak sends set-password email directly
  • [x] Environment -- prod/keycloak, commit 6d89b9fc4f
  • [x] Acceptance Criteria -- 3 criteria, all testable
  • [x] Related -- project reference present
  • [x] Fix Location -- NEW in v2: Keycloak admin console, Realm Settings, Email tab
  • [x] Fix Steps -- NEW in v2: 5-step manual procedure, marked not agent-executable
  • [x] Followup Scope -- NEW in v2: codify SMTP in pal-e-platform IaC

Traceability

  • [x] story:WS-S12 label -- "As an admin, I want to manage user accounts (reset passwords, view profiles) so that I can support parents directly"
  • [x] story note verified -- found in project-westside-basketball user-stories section under Admin (Marcus)
  • [ ] arch:basketball-api note MISSING -- [SCOPE] Create architecture note arch-basketball-api (systemic gap, not blocking)
  • [ ] arch:keycloak note MISSING -- [SCOPE] Create architecture note arch-keycloak (systemic gap, repeat finding)
  • [x] Forgejo issue -- forgejo_admin/basketball-api#373, open

File Targets

Bug template does not require explicit file targets. Code paths verified against codebase to confirm basketball-api code is correct:
  • [x] src/basketball_api/services/keycloak.py:118-146 -- trigger_set_password_email function confirmed, calls PUT execute-actions-email on line 137
  • [x] src/basketball_api/services/email.py:53-55 -- "No DB token" fallback warning matches log evidence
  • [x] src/basketball_api/services/keycloak.py:338 -- called during registration flow (create_keycloak_account_for_parent)
  • [x] src/basketball_api/routes/admin.py:610 -- called during announcement resend flow
  • [x] pal-e-platform/terraform/modules/keycloak/main.tf -- CONFIRMED: zero SMTP/email configuration in Keycloak Terraform module, validating the "not in IaC" finding

Repo Placement

RESOLVED in v2. Issue now clearly states: fix is manual Keycloak admin console operation, not a basketball-api code change. The issue is correctly filed on basketball-api (where the symptom manifests) and explicitly identifies the fix location as Keycloak admin console. Followup IaC ticket scoped for pal-e-platform.

Dependencies

No blocking dependencies. Gmail fallback keeps registration working (degraded mode). Fix is independent of any in-progress work.

Acceptance Criteria

3 criteria, all verifiable after manual SMTP configuration:
  • [x] "execute-actions-email returns 200/204" -- testable via manual registration
  • [x] "Root cause identified" -- already identified: missing Keycloak SMTP config
  • [x] "Gmail fallback warning no longer appears" -- verifiable via log grep

Blast Radius

trigger_set_password_email called from 4 locations: keycloak.py:338, admin.py:610, create_keycloak_accounts.py:175, backfill_password_reset.py:145. All handle failure gracefully (return False, log warning). Fix is upstream (Keycloak SMTP) so all callers benefit simultaneously with zero code changes.

Decomposition Assessment

Single manual config fix (5 steps in Keycloak admin console). No code changes. No decomposition needed. Not agent-executable.

Recommendation

All [BODY] recommendations from rounds 1 and 2 are resolved. Remaining items are systemic [SCOPE] gaps that do not block this ticket:
  • [SCOPE] Create architecture note arch-basketball-api (systemic gap across multiple tickets).
  • [SCOPE] Create architecture note arch-keycloak (systemic gap, repeat finding from review-785-2026-04-03).
No action needed to advance this ticket.