flarum/framework · error · ValidationException

avatar

Error message

avatar

What it means

The 'avatar.upload' custom endpoint on UserResource (POST /api/users/{id}/avatar) failed processing the avatar upload. This marks the avatar upload action: the request failed authentication, the editAvatar permission check, or the uploaded file could not be processed as a valid image.

Solutions

1. Ensure the request is authenticated and the user has permission to edit the target user's avatar (editAvatar ability)
2. Send multipart/form-data with a valid image file under the expected field name
3. Check the image passes size/format validation handled by the AvatarUploader

When it happens

Trigger: Thrown at framework/core/src/Api/Resource/UserResource.php:159 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of flarum/framework@4b939f6853 (2026-09-15). Data as JSON: /api/errors/25fe9e12b2ed1e43. Report an issue: GitHub.

Appendix: source

Thrown at framework/core/src/Api/Resource/UserResource.php:159

                ->authenticated()
                ->can('delete'),
            Endpoint\Show::make()
                ->defaultInclude(['groups'])
                ->eagerLoad(['groups']),
            Endpoint\Index::make()
                ->can('searchUsers')
                ->defaultInclude(['groups'])
                ->eagerLoad(['groups'])
                ->paginate(),
            Endpoint\Endpoint::make('avatar.upload')
                ->route('POST', '/{id}/avatar')
                ->authenticated()
                ->can('editAvatar')
                ->action(function (Context $context) {
                    $file = Arr::get($context->request->getUploadedFiles(), 'avatar');

                    if (! $file instanceof UploadedFileInterface) {
                        throw new ValidationException([
                            'avatar' => str_replace(':attribute', 'avatar', $this->translator->trans('validation.required')),
                        ]);
                    }

                    return $this->bus->dispatch(
                        new UploadAvatar((int) $context->modelId, $file, $context->getActor())
                    );
                }),
            Endpoint\Endpoint::make('avatar.delete')
                ->route('DELETE', '/{id}/avatar')
                ->authenticated()
                ->can('editAvatar')
                ->action(function (Context $context) {
                    return $this->bus->dispatch(
                        new DeleteAvatar(Arr::get($context->request->getQueryParams(), 'id'), $context->getActor())
                    );
                }),
        ];

View on GitHub (pinned to 4b939f6853)