AlistGo/alist · error

authentication required

Error message

authentication required

What it means

Returned by resolveUser (server/mcp/auth.go:106) when an MCP tool handler finds no *model.User under the context userKey. The auth middleware logs 'MCP auth failed' and passes the request through with no user, so this fires for requests whose token failed authentication (or was never sent) and later reached a tool requiring a user.

Source

Thrown at server/mcp/auth.go:106

	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)
	if err != nil {
		return ctx, "", err
	}
	meta, _ := op.GetNearestMeta(reqPath)
	ctx = context.WithValue(ctx, "meta", meta)
	ctx = context.WithValue(ctx, "user", user)
	return ctx, reqPath, nil
}

// checkAccess checks if user can access the path (read).
func checkAccess(user *model.User, reqPath string) error {

View on GitHub (pinned to 843d9dc814)

Solutions

1. Send a valid Authorization header/token with every MCP request
2. If a token was working, find the earlier 'MCP auth failed' log line naming the real reason
3. Make tool calls fail fast on missing auth instead of continuing the session

Example fix

// before
client.connect({ url: "http://host/mcp" })
// after
client.connect({ url: "http://host/mcp", headers: { Authorization: "Bearer <token>" } })

if cfg.Token == "" { return fmt.Errorf("MCP token not configured — request will fail with authentication required") }

if err != nil && strings.Contains(err.Error(), "authentication required") { checkToken(); sendFreshToken(); retryOnce() }

When it happens

Trigger: MCP tool call with a missing or blank Authorization header; a token that failed one of the authenticateToken checks (invalid, disabled user, etc.) while the connection itself was still accepted.

Common situations: MCP clients configured without auth; tokens silently expired mid-session; middleware ordering changes letting unauthenticated contexts reach tools.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

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/8973e3bcd4c69a33. Report an issue: GitHub.