{"record":{"id":"0cc0693df1798f0f","repo":"fatedier/frp","slug":"unexpected-error-when-creating-new-controller","errorCode":null,"errorMessage":"unexpected error when creating new controller","messagePattern":"unexpected error when creating new controller","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/service.go","lineNumber":830,"sourceCode":"\t\treturn nil, err\n\t}\n\n\tctl, err := NewControl(ctx, &SessionContext{\n\t\tRC:             svr.rc,\n\t\tPxyManager:     svr.pxyManager,\n\t\tPluginManager:  svr.pluginManager,\n\t\tAuthVerifier:   authVerifier,\n\t\tEncryptionKey:  svr.auth.EncryptionKey(),\n\t\tConn:           ctlConn,\n\t\tLoginMsg:       loginMsg,\n\t\tServerCfg:      svr.cfg,\n\t\tWireProtocol:   wireProtocol,\n\t\tUDPPacketCodec: udpPacketCodec,\n\t})\n\tif err != nil {\n\t\txl.Warnf(\"create new controller error: %v\", err)\n\t\t// don't return detailed errors to client\n\t\treturn nil, fmt.Errorf(\"unexpected error when creating new controller\")\n\t}\n\n\tif err := svr.ctlManager.Add(ctl); err != nil {\n\t\treturn ctl, err\n\t}\n\tctl.WaitForHandoff()\n\n\tactive, err := svr.ctlManager.Activate(ctl)\n\tif err != nil {\n\t\treturn ctl, err\n\t}\n\tif !active {\n\t\treturn ctl, errControlReplaced\n\t}\n\n\treturn ctl, nil\n}\n","sourceCodeStart":812,"sourceCodeEnd":848,"githubUrl":"https://github.com/fatedier/frp/blob/6c8a8d0a97d03b44e9528d30b30c70cb9d61b405/server/service.go#L812-L848","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the frps log for the paired 'create new controller error: %v' line — it contains the real cause","Verify the client connection is stable and not being dropped by a NAT/proxy during login","Confirm server resource limits (max proxies, ports, memory) are not exhausted","Retry the client login once transient conditions are ruled out; upgrade frps if the logged cause indicates a bug"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"// client side\nctl, err := svr.RegisterControl(conn, login, internal, proto, codec)\nif err != nil && strings.Contains(err.Error(), \"unexpected error when creating new controller\") {\n    // opaque by design: correlate with frps logs via run id / timestamp, then retry once\n    log.Warnf(\"control creation failed (server cause in frps log); retrying\")\n    time.Sleep(backoff.Next())\n    ctl, err = svr.RegisterControl(conn2, login, internal, proto, codec)\n}","preventionTips":["Ship structured frps logs so the 'create new controller error' detail is findable by run id","Exponential backoff on client login","Keep control connections on stable networks; enable transport.tls and heartbeat tuning to reduce mid-handshake drops"],"tags":["frp","control-connection","opaque-error","diagnostics"],"backgroundTag":null,"analyzedSha":"6c8a8d0a97d03b44e9528d30b30c70cb9d61b405","analyzedAt":"2026-08-15T06:53:27.215Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}