{"record":{"id":"3f093aa728a8a03d","repo":"XTLS/Xray-core","slug":"failed-to-build-mask-with-type-mask-type","errorCode":null,"errorMessage":"failed to build mask with type  + mask.Type","messagePattern":"failed to build mask with type  \\+ mask\\.Type","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/transport_internet.go","lineNumber":207,"sourceCode":"\t\t}\n\t\tconfig.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{\n\t\t\tProtocolName: \"hysteria\",\n\t\t\tSettings:     serial.ToTypedMessage(hs),\n\t\t})\n\t}\n\tif c.SocketSettings != nil {\n\t\tss, err := c.SocketSettings.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"Failed to build sockopt.\").Base(err)\n\t\t}\n\t\tconfig.SocketSettings = ss\n\t}\n\n\tif c.FinalMask != nil {\n\t\tfor _, mask := range c.FinalMask.Tcp {\n\t\t\tu, err := mask.Build(true)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, errors.New(\"failed to build mask with type \", mask.Type).Base(err)\n\t\t\t}\n\t\t\tconfig.Tcpmasks = append(config.Tcpmasks, serial.ToTypedMessage(u))\n\t\t}\n\t\tfor _, mask := range c.FinalMask.Udp {\n\t\t\tu, err := mask.Build(false)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, errors.New(\"failed to build mask with type \", mask.Type).Base(err)\n\t\t\t}\n\t\t\tconfig.Udpmasks = append(config.Udpmasks, serial.ToTypedMessage(u))\n\t\t}\n\t\tif c.FinalMask.QuicParams != nil {\n\t\t\tprofile := strings.ToLower(c.FinalMask.QuicParams.BbrProfile)\n\t\t\tswitch profile {\n\t\t\tcase \"\", string(bbr.ProfileConservative), string(bbr.ProfileStandard), string(bbr.ProfileAggressive):\n\t\t\t\tif profile == \"\" {\n\t\t\t\t\tprofile = string(bbr.ProfileStandard)\n\t\t\t\t}\n\t\t\tdefault:","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/transport_internet.go#L189-L225","documentation":"Thrown when a TCP mask entry under streamSettings.finalMask.tcp fails to build (mask.Build(true) errors). The error text interpolates mask.Type, so it tells you which mask implementation rejected its own configuration (e.g. an unrecognized or misconfigured TCP mask type). It stops config compilation immediately.","triggerScenarios":"Config contains \"finalMask\": { \"tcp\": [ { \"type\": \"<something>\", ... } ] } and the mask's Build() returns an error for that type's parameters.","commonSituations":"Using a mask type name not registered/supported by this build; supplying wrong per-type fields; configs ported from a fork with extra mask types.","solutions":["Check the mask.Type value in the error against the registered TCP mask types in the codebase; fix typos or unsupported types.","Validate the per-type fields required by that mask implementation.","Remove the offending mask entry to isolate whether other mask entries build fine."],"exampleFix":"// before\n\"finalMask\": { \"tcp\": [ { \"type\": \"typoMask\", \"window\": 10 } ] }\n// after\n\"finalMask\": { \"tcp\": [ { \"type\": \"windowMask\", \"window\": 10 } ] } // use a registered type","handlingStrategy":"validation","validationCode":"var validTcpMaskTypes = map[string]bool{\"window\": true /* ...populate from this build's registry... */}\n\nfunc tcpMasksValid(fm map[string]any) bool {\n    tcp, _ := fm[\"tcp\"].([]any)\n    for _, m := range tcp {\n        mm, _ := m.(map[string]any)\n        t, _ := mm[\"type\"].(string)\n        if !validTcpMaskTypes[t] { return false }\n    }\n    return true\n}","typeGuard":"func isFinalMaskTcpList(fm map[string]any) bool {\n    _, ok := fm[\"tcp\"].([]any)\n    return ok\n}","tryCatchPattern":"if err := doc.Build(); err != nil {\n    if strings.HasPrefix(err.Error(), \"failed to build mask with type\") {\n        // extract the type token from the message and report which entry failed\n    }\n    return err\n}","preventionTips":["Maintain an allow-list of mask types validated in CI against the deployed binary.","Name each mask entry in comments/templates so failures map to a source location.","Never carry mask blocks across forks without re-validating types."],"tags":["go","xray","config","tcp-mask","validation"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}