{"record":{"id":"1d1aed9553b8c762","repo":"fatedier/frp","slug":"start-new-visitor-connection-error-s","errorCode":null,"errorMessage":"start new visitor connection error: %s","messagePattern":"start new visitor connection error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/visitor/visitor.go","lineNumber":198,"sourceCode":"\t}\n\terr = visitorConn.WriteMsg(newVisitorConnMsg)\n\tif err != nil {\n\t\tvisitorConn.Close()\n\t\treturn nil, fmt.Errorf(\"send newVisitorConnMsg to server error: %v\", err)\n\t}\n\n\t_ = visitorConn.SetReadDeadline(time.Now().Add(10 * time.Second))\n\tvar newVisitorConnRespMsg msg.NewVisitorConnResp\n\terr = visitorConn.ReadMsgInto(&newVisitorConnRespMsg)\n\tif err != nil {\n\t\tvisitorConn.Close()\n\t\treturn nil, fmt.Errorf(\"read newVisitorConnRespMsg error: %v\", err)\n\t}\n\t_ = visitorConn.SetReadDeadline(time.Time{})\n\n\tif newVisitorConnRespMsg.Error != \"\" {\n\t\tvisitorConn.Close()\n\t\treturn nil, fmt.Errorf(\"start new visitor connection error: %s\", newVisitorConnRespMsg.Error)\n\t}\n\treturn visitorConn, nil\n}\n\nfunc wrapVisitorConn(conn io.ReadWriteCloser, cfg *v1.VisitorBaseConfig) (io.ReadWriteCloser, func(), error) {\n\trwc := conn\n\tif cfg.Transport.UseEncryption {\n\t\tvar err error\n\t\trwc, err = libio.WithEncryption(rwc, []byte(cfg.SecretKey))\n\t\tif err != nil {\n\t\t\treturn nil, func() {}, fmt.Errorf(\"create encryption stream error: %v\", err)\n\t\t}\n\t}\n\trecycleFn := func() {}\n\tif cfg.Transport.UseCompression {\n\t\trwc, recycleFn = libio.WithCompressionFromPool(rwc)\n\t}\n\treturn rwc, recycleFn, nil","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/fatedier/frp/blob/6c8a8d0a97d03b44e9528d30b30c70cb9d61b405/client/visitor/visitor.go#L180-L216","documentation":"The server answered the visitor's connection request with an explicit error string inside NewVisitorConnResp.Error. This is a server-side rejection, not a local failure: frps validated the request (proxy lookup, signature, negotiation) and refused it; the message string is the server's reason.","triggerScenarios":"Target proxy name not found on the server (the name built from user/serverUser/serverName has no matching stcp/xtcp proxy); SignKey mismatch because the visitor's secretKey differs from the server; timestamp skew beyond the allowed window; the target proxy does not accept visitors.","commonSituations":"Visitor's serverName does not match the proxy name of the serving frpc; visitor and server disagree on secretKey/auth token; client and server clocks drift so the timestamped signature is rejected; multi-user prefixes (user/serverUser) produce a name that differs from the registered proxy name.","solutions":["Compare the visitor's serverName with the frpc proxy name it targets; they must match exactly.","Verify the same secretKey (and auth token/user) is configured on the visitor, the proxy owner, and frps.","Sync clocks via NTP on client and server so the auth timestamp stays within tolerance.","In multi-user setups, check that the user/serverUser prefix logic produces the proxy name the server actually registered."],"exampleFix":"# frpc visitor config (TOML)\n# before\n[[visitors]]\nname = \"ssh-v\"\ntype = \"stcp\"\nserverName = \"ssh-wrong\"\nsecretKey = \"abc\"\n\n# after\n[[visitors]]\nname = \"ssh-v\"\ntype = \"stcp\"\nserverName = \"ssh\"   # must equal the owner's proxy name\nsecretKey = \"abc\"    # must equal the proxy's secretKey","handlingStrategy":"validation","validationCode":"// Before starting the visitor, sanity-check the name it will target\nbase := visitorCfg.GetBaseConfig()\ntarget := naming.BuildTargetServerProxyName(user, base.ServerUser, base.ServerName)\n_ = target // cross-check against the registered proxy names of the owner client","typeGuard":null,"tryCatchPattern":"if _, err := v.newVisitorConn(ctx); err != nil {\n    if strings.Contains(err.Error(), \"start new visitor connection error\") {\n        // server rejection: config problem — do NOT retry blindly; fix name/key\n        return err\n    }\n}","preventionTips":["Keep visitor serverName identical to the owner proxy name","Share secretKey via one source of truth across owner, visitor, and server","Sync clocks with NTP on all frp hosts"],"tags":["config","auth","visitor","server-rejection"],"backgroundTag":null,"analyzedSha":"6c8a8d0a97d03b44e9528d30b30c70cb9d61b405","analyzedAt":"2026-08-15T06:53:27.215Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}