fatedier/frp · error

unexpected error when creating new controller

Error message

unexpected error when creating new controller

What it means

Service.RegisterControl wraps any failure of NewControl in this opaque error, deliberately hiding the underlying cause from the client (the real reason is logged server-side with xl.Warnf("create new controller error")). NewControl can fail while setting up the control session (e.g. resource limits, closed connection, invalid session parameters), and the wrapper prevents leaking internal details over the wire.

Source

Thrown at server/service.go:830

		return nil, err
	}

	ctl, err := NewControl(ctx, &SessionContext{
		RC:             svr.rc,
		PxyManager:     svr.pxyManager,
		PluginManager:  svr.pluginManager,
		AuthVerifier:   authVerifier,
		EncryptionKey:  svr.auth.EncryptionKey(),
		Conn:           ctlConn,
		LoginMsg:       loginMsg,
		ServerCfg:      svr.cfg,
		WireProtocol:   wireProtocol,
		UDPPacketCodec: udpPacketCodec,
	})
	if err != nil {
		xl.Warnf("create new controller error: %v", err)
		// don't return detailed errors to client
		return nil, fmt.Errorf("unexpected error when creating new controller")
	}

	if err := svr.ctlManager.Add(ctl); err != nil {
		return ctl, err
	}
	ctl.WaitForHandoff()

	active, err := svr.ctlManager.Activate(ctl)
	if err != nil {
		return ctl, err
	}
	if !active {
		return ctl, errControlReplaced
	}

	return ctl, nil
}

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Check the frps log for the paired 'create new controller error: %v' line — it contains the real cause
2. Verify the client connection is stable and not being dropped by a NAT/proxy during login
3. Confirm server resource limits (max proxies, ports, memory) are not exhausted
4. Retry the client login once transient conditions are ruled out; upgrade frps if the logged cause indicates a bug

// client side
ctl, err := svr.RegisterControl(conn, login, internal, proto, codec)
if err != nil && strings.Contains(err.Error(), "unexpected error when creating new controller") {
    // opaque by design: correlate with frps logs via run id / timestamp, then retry once
    log.Warnf("control creation failed (server cause in frps log); retrying")
    time.Sleep(backoff.Next())
    ctl, err = svr.RegisterControl(conn2, login, internal, proto, codec)
}

When it happens

Trigger: NewControl returning a non-nil error for any reason — common causes include the control connection being closed mid-handshake, exceeding server-side resource/proxy limits, or invalid SessionContext contents. The client only sees 'unexpected error when creating new controller'; the specifics appear only in frps logs.

Common situations: Client disconnects during login; frps under resource pressure; plugin or proxy manager failures during controller init; any transient condition where the raw error must be diagnosed from the server log rather than the client.

Related errors

• exec configuration is required when type is 'exec'
• file path cannot be empty
• exec command cannot be empty
• exec env name cannot be empty
• exec env name cannot contain '='

AI-assisted analysis of fatedier/frp@6c8a8d0a97 (2026-08-15). Data as JSON: /api/errors/0cc0693df1798f0f. Report an issue: GitHub.