Fix avatar change issues in Jira Data Center

Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.

Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Summary

Users are unable to change their avatars and receive the error message

"Error occurred while creating avatar, please contact your Jira administrators".

Environment

Jira Data Center all versions

Diagnosis

  • When attempting to upload an image for a user avatar from the user profile page, clicking on confirm results in the error message: "Error occurred while creating avatar, please contact your Jira administrators".

    Avatar creation page displays the "Error occurred while creating avatar, please contact your Jira administrators" in red.
  • The following error can be found in the atlassian-jira.log:

url: /j9170/rest/api/latest/user/avatar; user: admin ERROR admin 843x197x1 ol4mxd 0:0:0:0:0:0:0:1 /rest/api/latest/user/avatar [c.a.jira.avatar.AvatarPickerHelperImpl] Unable to create avatar. java.nio.file.FileAlreadyExistsException: /Users/test/jira-home/atlassian-jira-software-9.17.0/data/avatars
url: /j9170/rest/api/latest/user/avatar; user: admin ERROR admin 843x197x1 ol4mxd 0:0:0:0:0:0:0:1 /rest/api/latest/user/avatar [c.a.j.rest.exception.ExceptionInterceptor] Returning internal server error in response java.lang.reflect.InvocationTargetException Caused by: com.atlassian.jira.rest.v2.issue.RESTException(Internal Server Error) at com.atlassian.jira.rest.v2.issue.AvatarResourceHelper.throwWebException(AvatarResourceHelper.java:445)
  • Use the directory listing for the "avatars" directory in <Jira_Home>/data, to check if the directory is a symbolic link.

Related Information

If you see no error message on the profile page, but the avatar reverts back to the previous image, please refer to Unable to Upload User Avatar

Cause

Jira needs the avatars directory to be a real folder, not a shortcut. When you upload an avatar, Jira tries to create a new folder at that spot. If there's already a shortcut there, you'll get a FileAlreadyExistsException error.

Solution

  1. Stop Jira.

  2. Back up the /avatars directory located in the Jira home.

  3. Remove the symbolic link.

  4. Start Jira.

Updated on September 26, 2025

Still need help?

The Atlassian Community is here for you.