What causes "Failed to read user profile: {str(e)}" in bytedance/deer-flow?

Check `get_paths().user_md_file` on disk: permissions, encoding, that it is a regular file

bytedance/deer-flow · error · HTTPException

Failed to read user profile: {str(e)}

Error message

Failed to read user profile: {str(e)}

What it means

Catch-all 500 on GET `/user-profile`: reading `paths.user_md_file` failed unexpectedly. A missing USER.md is normal and returns `content: null` (the `.exists()` check handles that), so this 500 means an actual IO error — permission denied, an unreadable file (I/O error, encoding failure on invalid UTF-8), or the path being a directory.

Source

Thrown at backend/app/gateway/routers/agents.py:501

    description="Read the global USER.md file that is injected into all custom agents.",
)
async def get_user_profile() -> UserProfileResponse:
    """Return the current USER.md content.

    Returns:
        UserProfileResponse with content=None if USER.md does not exist yet.
    """
    _require_agents_api_enabled()

    try:
        user_md_path = get_paths().user_md_file
        if not user_md_path.exists():
            return UserProfileResponse(content=None)
        raw = user_md_path.read_text(encoding="utf-8").strip()
        return UserProfileResponse(content=raw or None)
    except Exception as e:
        logger.error(f"Failed to read user profile: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to read user profile: {str(e)}")


@router.put(
    "/user-profile",
    response_model=UserProfileResponse,
    summary="Update User Profile",
    description="Write the global USER.md file that is injected into all custom agents.",
)
async def update_user_profile(request: UserProfileUpdateRequest) -> UserProfileResponse:
    """Create or overwrite the global USER.md.

    Args:
        request: The update request with the new USER.md content.

    Returns:
        UserProfileResponse with the saved content.
    """
    _require_agents_api_enabled()

View on GitHub (pinned to 1dd6ba1acb)

Solutions

Check `get_paths().user_md_file` on disk: permissions, encoding, that it is a regular file
Rewrite the file as UTF-8 or delete it (absence is a supported state returning null)
Fix mount/ownership on the base_dir volume

Example fix

# before: file saved as latin-1 -> UnicodeDecodeError -> 500
# after
iconv -f latin-1 -t utf-8 USER.md -o USER.md.utf8 && mv USER.md.utf8 USER.md

Defensive patterns

Strategy: fallback

Try / catch

try { return await api.getUserProfile(); }
catch (e) {
  if (e.status === 500 && /read user profile/.test(e.detail)) {
    return { content: null, degraded: true }; // missing profile is a valid empty state anyway
  }
  throw e;
}

Prevention

Ensure USER.md is always written as UTF-8
Check file permissions on the profile path during deployment smoke tests
A 500 here means the file exists but is unreadable — inspect encoding/permissions, not existence

When it happens

Trigger: USER.md owned by another user with no read permission; a USER.md written in a non-UTF-8 encoding causing decode failure; the profile path replaced by a directory via a bad mount.

Common situations: Volume permission drift in containers; operators writing USER.md with a tool that saved latin-1; symlink loops.

Related errors

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/6482cc1de3710501. Report an issue: GitHub.