Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Troubleshooting license upload errors


Customers may report encountering the following error message when uploading a license to their GitLab Self-Managed instance:

During the year before this license started, this GitLab installation had 286 active users, exceeding this license's limit of 250 by 36 users. Please upload a license for at least 286 users or contact sales at [redacted]@gitlab.com.

This error is shown if any of the following 3 values are incorrect:

Key Field Definition & source of truth
Users count GitLab 13.6 and later We can identify the minimum amount via the billable.users command: sudo gitlab-rails runner 'p User.billable.count'

GitLab 13.5 and before We identify the minimum amount via the active.users command: sudo gitlab-rails runner 'p User.active.count'
Previous users count We can try to assume based on internal numbers such as CustomerDot or usage. But this cannot be certain since multiple licenses may be generated for one period. Instead, the best identifier is the system itself. For this we request a screenshot of the user statistics panel from Admin Area -> Overview -> Dashboard. The Previous users count = Users in License in the widget on the top left.
True-up count The best identifier for this value is to take Max Users - Previous users count. We recommend using the historical.max command: sudo gitlab-rails runner 'p ::HistoricalData.max_historical_user_count' for the Max count.

Important: As of GitLab 13.9 the max_historical_user_count method requires two arguments, a range of dates specified by from: and to:: sudo gitlab-rails runner 'p ::HistoricalData.max_historical_user_count(from: "2020-01-01", to: "2021-01-01")'.

Note: For Ultimate licenses, guest users are not counted in the licensed user count. Therefore, in GitLab 13.5 and before, the User.active.count will be a greater number than the Active Users count displayed in the Admin UI dashboard. In GitLab 13.6+ User.billable.count will accurately exclude guests from the count. This can be confusing in a situation where the customer is downgrading from Ultimate or if they have an Ultimate trial, because they need a license for User.active.count instead of what is displayed for Active Users.

You can use the Zendesk Subscriptions::Active Users macro to ask the customer for this information.

Examples

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

Git is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license