User avatar never renders in `Header` — reads `authenticatedUser.avatar`, a field the platform has never provided

[brian-smith-tcril]

Important

🤖 Generated by Claude

This issue — the investigation, evidence, and write-up — was produced by Claude (Claude Code), reviewed by a human before posting. Commit references, dates, and file paths were gathered programmatically from git history and the source repos; please still sanity-check specifics before acting on them.

---

Summary

The user avatar in the desktop and mobile user-menu toggles (DesktopUserMenuToggle / MobileUserMenuToggle) never displays a real image — it always falls back to the placeholder AvatarIcon.

The root cause is a single field-name mismatch: src/Header.jsx reads authenticatedUser.avatar, but no layer of the Open edX stack has ever populated an avatar field on the authenticated user. The profile image has always lived at authenticatedUser.profileImage.imageUrlMedium (populated by hydrateAuthenticatedUser()).

The Studio header hit the identical bug and was fixed in commit 38a68e5 ("fix: show hydrated profile avatars in Studio header"). The same fix was never applied to the main desktop/mobile Header.

Note: this issue is a write-up of the investigation only. It intentionally does not include a fix PR yet.

Symptom & scope

Header	Avatar source	Status
Header → DesktopHeader → DesktopUserMenuToggle	authenticatedUser.avatar	❌ broken
Header → MobileHeader → MobileUserMenuToggle	authenticatedUser.avatar	❌ broken
StudioHeader → UserMenu	authenticatedUser.avatar || profileImage.imageUrlMedium	✅ fixed (38a68e5)
LearningHeader	renders no avatar (username only)	— n/a

Root cause

The plumbing inside this repo is correct end-to-end:

Header.jsx → DesktopHeaderSlot → DesktopHeader → DesktopUserMenuToggleSlot → DesktopUserMenuToggle → Avatar src={avatar}

The break is the source value at the top:

// src/Header.jsx
avatar: authenticatedUser !== null ? authenticatedUser.avatar : null,

authenticatedUser.avatar is effectively always undefined, so Avatar renders the placeholder icon.

Why avatar is never set — evidence across the whole stack

Layer	What it actually provides	avatar?
edx-platform accounts API /api/user/v1/accounts/{username}	profile_image: { has_image, image_url_full/large/medium/small } — shape stable since March 2015 (46b63164a)	❌ never
@edx/frontend-platform hydrateAuthenticatedUser()	camelCases the above → profileImage: { hasImage, imageUrlMedium, … } via setAuthenticatedUser({ ...user, ...camelCaseObject(response.data) })	❌ never
@edx/frontend-platform JWT-decoded user	{ email, userId, username, roles, administrator, name }	❌ never
@edx/frontend-auth (legacy) userAccount model	profileImage: { imageUrlMedium, imageUrlLarge }	❌ never
@edx/frontend-base v1.1.0 / v2.0.0 (the versions this repo pinned in 2019)	getAuthenticatedUser returns exactly { userId, username, roles, administrator } (explicit field pick — no spread, so a JWT claim couldn't leak through either)	❌ never

A live sample of the accounts endpoint today confirms it — profile_image.image_url_medium present, has_image: true, and no avatar key.

The correct pattern

Mirror the Studio header fix (src/studio-header/StudioHeader.tsx):

const authenticatedUserAvatar = authenticatedUser?.avatar
  || (profileImage?.hasImage ? profileImage.imageUrlMedium : null);

Note the profileImage.hasImage guard — when the user has no uploaded image the API still returns profile_image with has_image: false and default-image URLs, so the guard matters.

Two failure modes across consumers

Profile-image data is only present if the MFE opts into hydration — initialize({ hydrateAuthenticatedUser: true }), which defaults to false. So consumers fail in one of two ways:

1. Wrong field — MFEs that do hydrate (e.g. frontend-app-account, frontend-app-profile) have authenticatedUser.profileImage available, but the header reads the nonexistent .avatar.
2. Not hydrated — MFEs that don't opt in (e.g. frontend-app-learner-dashboard) never fetch profileImage at all, so even a corrected field read would need hydration enabled.

Historical provenance (why the code looks like this)

• afe6705 (2019-09-13, initial commit): original SiteHeader.jsx destructured avatar from @edx/frontend-base's AuthenticationContext. That context never supplied avatar — and the author's own example/test mocks only set { userId, username, administrator }.
• f9d1734 (2019-09-18, "upgrading to frontend-base 2.0.0"): the frontend-base 2.0 migration converted the destructured avatar into avatar: authenticatedUser.avatar — this is where the current form was introduced.
• 57e05c4 (2019-11-04, Modernize build and fix the anonymous header #26): added the !== null guard only.
• Likely origin of the field name: frontend-app-learning once contained a design doc docs/api-strawperson.js (since deleted) sketching a proposed user: { …, avatar: String } API shape that was never implemented. The header appears to have been written against that aspirational contract, while the shipped data always lived under profileImage.

So the avatar read has been dead on arrival since the repo's first commit; no dependency bump ever made it live.

Ecosystem audit (for completeness)

A full git-history pickaxe (git log --all -S avatar) across all 13 frontend-app-* consumers of this package found that no MFE has ever injected an avatar field onto authenticatedUser (no manual AppContext.Provider, no custom auth/hydration handler) — in current code or anywhere in history. Every avatar occurrence is incidental (Paragon <Avatar>, CSS class names, forum/API profile-image data, package-lock noise).

Two notable findings:

• frontend-app-account and frontend-app-profile previously rendered their own vendored headers that read the image correctly from state.userAccount.profileImage — and regressed to a missing avatar when they adopted @edx/frontend-component-header.
• The real image data is consistently sourced from profileImage.imageUrlMedium everywhere in the ecosystem (e.g. frontend-app-learner-portal-enterprise's AvatarDropdown), making this component's avatar read the lone outlier.

Suggested direction (fix deferred)

1. In src/Header.jsx, fall back to the hydrated profile image, mirroring the Studio fix and guarding on hasImage:

   avatar: authenticatedUser
     ? (authenticatedUser.avatar
        || (authenticatedUser.profileImage?.hasImage
            ? authenticatedUser.profileImage.imageUrlMedium
            : null))
     : null,

2. Document that consuming MFEs must call initialize({ hydrateAuthenticatedUser: true }) for the image to be available (relevant to frontend-app-learner-dashboard and any other full-Header consumer that doesn't hydrate today).

Affected files

• src/Header.jsx — the buggy read (feeds both desktop and mobile).
• src/desktop-header/DesktopUserMenuToggle.jsx, src/mobile-header/MobileUserMenuToggle.jsx — consume the avatar prop.
• Reference for the correct pattern: src/studio-header/StudioHeader.tsx (fixed in 38a68e5).

[brian-smith-tcril]

Important

🤖 Generated by Claude (Claude Code), human-reviewed before posting.

Relationship to #670 (Studio header fix)

The Studio header was fixed for exactly this bug in #670 ("fix: show hydrated profile avatars in Studio header", merged 2026-05-07), which added the profileImage.imageUrlMedium fallback that this issue recommends generalizing to the desktop/mobile Header. That PR explicitly scopes the LMS header out as future work:

Future work: Avatar needs to be fixed for the LMS / new Instructor Dashboard as well. Those were left to keep the scope of this PR tight.

That "LMS header" is the desktop/mobile Header path this issue covers — so this issue can serve as the tracking issue for #670's deferred work.

One correction to carry forward

#670's description frames keeping authenticatedUser.avatar first as preserving "the legacy header avatar contract." Our investigation (detailed above) found there is no legacy avatar contract — authenticatedUser.avatar has never been populated by any layer of the stack at any point in history:

• No version of @edx/frontend-base (v1.1.0 / v2.0.0), @edx/frontend-auth, or @edx/frontend-platform has ever set it.
• The edx-platform accounts API has never returned it (the field has always been profile_image, since 2015).
• A full git-history pickaxe across all 13 frontend-app-* consumers found no MFE ever injected it onto authenticatedUser.

So the authenticatedUser?.avatar || branch (in both the merged Studio fix and any future desktop/mobile fix) is effectively dead code in the standard Open edX stack — harmless as the first term of an ||, but it cannot be truthy unless a consumer hand-injects the field, which none do. The profileImage.imageUrlMedium fallback does 100% of the real work. Worth keeping in mind so the desktop/mobile fix isn't justified on the same "preserving a working contract" premise — there's nothing working to preserve.