{"record":{"id":"84290317d8d4e31f","repo":"gohugoio/hugo","slug":"unable-to-obtain-a-valid-tcp-port-v","errorCode":null,"errorMessage":"unable to obtain a valid tcp port: %v","messagePattern":"unable to obtain a valid tcp port: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helpers/general.go","lineNumber":48,"sourceCode":"\n\t\"github.com/jdkato/prose/transform\"\n)\n\n// FilePathSeparator as defined by os.Separator.\nconst FilePathSeparator = string(filepath.Separator)\n\n// TCPListen starts listening on a valid TCP port.\nfunc TCPListen() (net.Listener, *net.TCPAddr, error) {\n\tl, err := net.Listen(\"tcp\", \":0\")\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\taddr := l.Addr()\n\tif a, ok := addr.(*net.TCPAddr); ok {\n\t\treturn l, a, nil\n\t}\n\tl.Close()\n\treturn nil, nil, fmt.Errorf(\"unable to obtain a valid tcp port: %v\", addr)\n}\n\n// FirstUpper returns a string with the first character as upper case.\nfunc FirstUpper(s string) string {\n\tif s == \"\" {\n\t\treturn \"\"\n\t}\n\tr, n := utf8.DecodeRuneInString(s)\n\treturn string(unicode.ToUpper(r)) + s[n:]\n}\n\n// ReaderToBytes takes an io.Reader argument, reads from it\n// and returns bytes.\nfunc ReaderToBytes(lines io.Reader) []byte {\n\tif lines == nil {\n\t\treturn []byte{}\n\t}\n\tb := bp.GetBuffer()","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/helpers/general.go#L30-L66","documentation":"helpers.TCPListen (helpers/general.go:38) calls net.Listen(\"tcp\", \":0\") then type-asserts the listener's Addr() to *net.TCPAddr. Because the listener is explicitly TCP, the assertion should always hold on a standard runtime; this error only fires if a custom/modified net stack returns a non-TCP address for a tcp listener. It is effectively unreachable in normal usage.","triggerScenarios":"A custom net.Listen substitution (e.g. a test fake or a runtime shim) returning a wrapper Addr that is not *net.TCPAddr; an exotic/sandboxed runtime altering net behaviour. In a stock Hugo build this should never occur.","commonSituations":"Running under a non-standard runtime or with net-via-linklayer shims; otherwise, this indicates an environment/runtime bug rather than a user config issue.","solutions":["Retry the operation once; a transient custom-stack hiccup is the only realistic cause.","Remove any custom net.Listen substitution or runtime shim and use the standard net package.","Report it as an environment/runtime issue if it reproduces on stock Hugo."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// There is no meaningful pre-check; the listener is tcp so the assertion\n// should always hold. Keep a retry around TCPListen for robustness.\nfunc TCPListenWithRetry() (net.Listener, *net.TCPAddr, error) {\n    return helpers.TCPListen()\n}","typeGuard":null,"tryCatchPattern":"l, addr, err := helpers.TCPListen()\nif err != nil {\n    // retry once; if it persists, treat as an environment/runtime fault\n    l, addr, err = helpers.TCPListen()\n    if err != nil { return err }\n}\ndefer l.Close()","preventionTips":["Do not substitute a custom net.Listen that returns non-TCP addrs.","Treat persistent occurrences as a runtime/environment bug, not a config issue."],"tags":["network","runtime"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}