Custom AVATAR_URL and bookstack:refresh-avatar result in default user_avatar.png #5480

New Issue

OVERLORD · 2026-02-05T10:05:51+03:00

OVERLORD commented

2026-02-05 10:05:51 +03:00

Originally created by @lukoerfer on GitHub (Nov 5, 2025).

Attempted Debugging

I have read the debugging page

Searched GitHub Issues

I have searched GitHub for the issue.

Describe the Scenario

We want to customize the avatars of our users in our BookStack instance to a solution hosted in our internal network. We found a small project that provides a web server configuration to serve some prepared images in a similar way as the Gravatar API. After setting up the web server we changed the variable AVATAR_URL in the .env file of our BookStack instance to the URL of this web server, so it basically looks like this:

AVATAR_URL=https://avatars.mycompany.com/avatar/${hash}?s=${size}&d=identicon

Afterwards, we try to refresh the avatars of our users by calling the following command:

php artisan bookstack:refresh-avatar --email=user@mycompany.com -f

In the output of the command it shows that BookStack is trying to fetch an avatar image from avatars.mycompany.com and the command finishes successfully and without an error message.

However, the avatar image that we can fetch from the address using the browser does not show in BookStack. Instead for all users with a mail address that we pass to the command above the avatar image in BookStack changes the avatar image changes from the colorful generated image to the default avatar image {BASE_URL}/user_avatar.png. So it seems like the command has an effect, but BookStack is not able to process the image provided by the web server and therefor falls back to the default image. Are there any hidden requirements to the images provided via the AVATAR_URL?

When changing the AVATAR_URL so that no images are provided via the URL, the command bookstack:refresh-avatar actually shows some error message that the image could not be fetched. In this case, the avatar image remains the colorful generated image.

Exact BookStack Version

v25.07.3

Log Content

Hosting Environment

We first encountered this issue in an older version of BookStack that was running on PHP 8.1.
Since we wanted to make sure that the issue is not already fixed in a newer version of BookStack, we updated our instance to the newest version v25.07.3 and also updated PHP to version 8.3, which was necessary because BookStack v25.02 and higher requires at least PHP 8.2.
We installed (and updated) BookStack manually using Git on a virtual machine based on Ubuntu 22.04 and with an Apache2 proxy.

Originally created by @lukoerfer on GitHub (Nov 5, 2025). ### Attempted Debugging - [x] I have read the debugging page ### Searched GitHub Issues - [x] I have searched GitHub for the issue. ### Describe the Scenario We want to customize the avatars of our users in our BookStack instance to a solution hosted in our internal network. We found a [small project](https://github.com/isotes/static-gravatar-server) that provides a web server configuration to serve some prepared images in a similar way as the Gravatar API. After setting up the web server we changed the variable `AVATAR_URL` in the `.env` file of our BookStack instance to the URL of this web server, so it basically looks like this: ``` AVATAR_URL=https://avatars.mycompany.com/avatar/${hash}?s=${size}&d=identicon ``` Afterwards, we try to refresh the avatars of our users by calling the following command: ``` php artisan bookstack:refresh-avatar --email=user@mycompany.com -f ``` In the output of the command it shows that BookStack is trying to fetch an avatar image from `avatars.mycompany.com` and the command finishes successfully and without an error message. However, the avatar image that we can fetch from the address using the browser does not show in BookStack. Instead for all users with a mail address that we pass to the command above the avatar image in BookStack changes the avatar image changes from the colorful generated image to the default avatar image `{BASE_URL}/user_avatar.png`. So it seems like the command has an effect, but BookStack is not able to process the image provided by the web server and therefor falls back to the default image. Are there any hidden requirements to the images provided via the `AVATAR_URL`? When changing the `AVATAR_URL` so that no images are provided via the URL, the command `bookstack:refresh-avatar` actually shows some error message that the image could not be fetched. In this case, the avatar image remains the colorful generated image. ### Exact BookStack Version v25.07.3 ### Log Content ```text ``` ### Hosting Environment We first encountered this issue in an older version of BookStack that was running on PHP 8.1. Since we wanted to make sure that the issue is not already fixed in a newer version of BookStack, we updated our instance to the newest version v25.07.3 and also updated PHP to version 8.3, which was necessary because BookStack v25.02 and higher requires at least PHP 8.2. We installed (and updated) BookStack manually using Git on a virtual machine based on Ubuntu 22.04 and with an Apache2 proxy.

OVERLORD added the 🐕 Support label 2026-02-05 10:05:51 +03:00

OVERLORD commented

2026-02-05 10:05:53 +03:00

@metinbaris commented on GitHub (Nov 14, 2025):

Hello @lukoerfer

Does the image url exists in the server?
Url parameters should be md5 of given user email and size default 500 maybe this could be optional in the as code future

But currently it should work like this, the url for your case the sever should have:
https://avatars.mycompany.com/avatar/cd7d80f54c3d4933d02e31af8ba39f22?s=500&d=identicon

@metinbaris commented on GitHub (Nov 14, 2025): Hello @lukoerfer Does the image url exists in the server? Url parameters should be md5 of given user email and size default 500 maybe this could be optional in the as code future But currently it should work like this, the url for your case the sever should have: `https://avatars.mycompany.com/avatar/cd7d80f54c3d4933d02e31af8ba39f22?s=500&d=identicon`

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#5480