AlistGo/alist · error

failed to load roles: %w

Error message

failed to load roles: %w

What it means

Returned by loadRoles (server/mcp/auth.go:95) when the authenticated user has roles (len(user.Role) > 0) but op.GetRolesByUserID(user.ID) fails. Authentication succeeded; enriching the user with role details hit a database error, and the wrapped %w carries the underlying cause.

Source

Thrown at server/mcp/auth.go:95

	if claims.PwdTS != user.PwdTS {
		return nil, fmt.Errorf("password has been changed")
	}
	if user.Disabled {
		return nil, fmt.Errorf("user is disabled")
	}

	if err := loadRoles(user); err != nil {
		return nil, err
	}
	return user, nil
}

func loadRoles(user *model.User) error {
	if len(user.Role) > 0 {
		roles, err := op.GetRolesByUserID(user.ID)
		if err != nil {
			return fmt.Errorf("failed to load roles: %w", err)
		}
		user.RolesDetail = roles
	}
	return nil
}

// resolveUser extracts the authenticated user from context.
func resolveUser(ctx context.Context) (*model.User, error) {
	user, ok := ctx.Value(userKey).(*model.User)
	if !ok || user == nil {
		return nil, fmt.Errorf("authentication required")
	}
	return user, nil
}

// buildFsContext resolves path and sets meta in context for fs operations.
func buildFsContext(ctx context.Context, user *model.User, path string) (context.Context, string, error) {
	reqPath, err := user.JoinPath(path)

View on GitHub (pinned to 843d9dc814)

Solutions

1. Check the wrapped error in server logs for the real DB cause
2. Verify migrations for the roles tables completed
3. If transient (timeout, pool exhaustion), retry after the DB recovers
4. Cap MCP client concurrency if connection exhaustion is reproducible

if err != nil && strings.Contains(err.Error(), "failed to load roles") { backoff.Retry(call, 3) }

When it happens

Trigger: Database fails or times out exactly between the user lookup and the roles query; the role-mapping table is missing or corrupted by a partial migration; connection pool exhaustion under load.

Common situations: Migrations that created the users table but not the role-mapping table; transient DB drops during deploys; concurrent MCP bursts exhausting connections.

Related errors

• failed to get admin: %w
• failed to get guest: %w
• guest user is disabled
• invalid token: %w
• user not found: %w

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