AlistGo/alist · error · ErrChangeDefaultRole

cannot modify admin role

Error message

cannot modify admin role

What it means

ErrChangeDefaultRole ('cannot modify admin role') is a sentinel in internal/errs/role.go. The user/role management API refuses modifications that would alter the built-in admin role, because admin is the bootstrap super-user role whose identity and privileges must stay fixed.

Source

Thrown at internal/errs/role.go:6

package errs

import "errors"

var (
	ErrChangeDefaultRole = errors.New("cannot modify admin role")
)

View on GitHub (pinned to 843d9dc814)

Solutions

1. Skip the built-in admin role in any batch role operations (filter by role ID/name)
2. Create a separate custom role with the desired permissions instead of editing admin
3. If different admin-level privileges are needed, assign users a new role rather than mutating admin

Example fix

// before
for _, r := range roles { updateRole(r) }

// after
for _, r := range roles {
    if r.Name == "admin" { continue }
    updateRole(r)
}

// skip the built-in admin role before role mutations
if r.ID == 1 || r.Name == "admin" { // adjust to your admin-role identity
    return errs.ErrChangeDefaultRole
}

func isAdminRole(r *model.Role) bool {
    return r != nil && r.Name == "admin"
}

if err := updateRole(r); err != nil {
    if errors.Is(err, errs.ErrChangeDefaultRole) {
        // skip: built-in admin role is immutable by design
    }
}

When it happens

Trigger: Calling the role update/delete endpoint with the admin role's ID; attempting to rename admin, change its permissions, or delete it via the admin role endpoints.

Common situations: Automation scripts iterating over all roles and blindly updating each one; UI attempts to clean up roles; attempts to demote or delete the last admin and lock everyone out. The guard exists precisely to prevent that lockout.

Related errors

• oss: chunkNum invalid
• clientID and clientSecret are required in client_credentials
• share_ids is required
• failed to refresh token: refresh token is empty
• failed to refresh token: sub not match

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/cc78b7096c8d23c6. Report an issue: GitHub.