{"record":{"id":"5831fc0702c69535","repo":"tokio-rs/tokio","slug":"unexpected-xucred-version-from-local-peercred","errorCode":null,"errorMessage":"unexpected xucred version from LOCAL_PEERCRED","messagePattern":"unexpected xucred version from LOCAL_PEERCRED","errorType":"exception","errorClass":"io::Error","httpStatus":null,"severity":"error","filePath":"tokio/src/net/unix/ucred.rs","lineNumber":263,"sourceCode":"                &mut len,\n            );\n\n            if ret != 0 {\n                return Err(io::Error::last_os_error());\n            }\n            if len as usize != size_of::<xucred>() {\n                return Err(io::Error::new(\n                    io::ErrorKind::InvalidData,\n                    \"unexpected xucred size from LOCAL_PEERCRED\",\n                ));\n            }\n\n            let xucred = xucred.assume_init();\n\n            // Match `getpeereid(3)` and reject any `xucred` whose version we\n            // don't know how to interpret.\n            if xucred.cr_version != XUCRED_VERSION {\n                return Err(io::Error::new(\n                    io::ErrorKind::InvalidData,\n                    \"unexpected xucred version from LOCAL_PEERCRED\",\n                ));\n            }\n\n            // `cr_pid` is populated by the kernel since FreeBSD 13. PID 0 is\n            // the kernel scheduler and never a real userland peer, so we\n            // surface it as `None` rather than a misleading `Some(0)`.\n            let pid = match xucred.cr_pid__c_anonymous_union.cr_pid {\n                0 => None,\n                p => Some(p as unix::pid_t),\n            };\n\n            // `xucred` carries the effective uid in `cr_uid` and the effective\n            // gid in `cr_groups[0]`, matching what `getpeereid(2)` returns.\n            Ok(super::UCred {\n                uid: xucred.cr_uid as unix::uid_t,\n                gid: xucred.cr_groups[0] as unix::gid_t,","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/tokio-rs/tokio/blob/625954f365727668cb02d04172b34f1149637728/tokio/src/net/unix/ucred.rs#L245-L281","documentation":"Thrown by tokio's FreeBSD peer-credential retrieval for Unix sockets. After reading LOCAL_PEERCRED into an xucred struct, tokio verifies cr_version equals XUCRED_VERSION; a mismatch means the kernel returned a credential layout tokio cannot interpret safely. It mirrors getpeereid(3) which rejects unknown credential versions.","triggerScenarios":"Calling UCred::from_LOCAL_PEERCRED (via UnixStream::peer_cred / UnixListener peer credential APIs) on FreeBSD where the kernel's xucred version differs from the constant tokio was compiled against.","commonSituations":"Running a tokio binary built against one FreeBSD major version on a different major version whose xucred ABI changed; running on an older FreeBSD that reports a lower cr_version; cross-version jail or compatibility layers that synthesize credentials.","solutions":["Rebuild tokio (and your crate) on the exact FreeBSD version where it runs so XUCRED_VERSION matches the kernel.","Upgrade tokio to a release that supports the xucred version your kernel emits.","Avoid peer_cred on the affected host and obtain peer credentials through an out-of-band mechanism (e.g. SO_PEERCRED-equivalent handshake in your protocol).","If pinned on a mismatched FreeBSD, run inside a jail/kernel of a supported version."],"exampleFix":"// before\nlet cred = stream.peer_cred()?;\n// after (guard against the platform mismatch)\nlet cred = match stream.peer_cred() {\n    Ok(c) => c,\n    Err(e) if e.kind() == io::ErrorKind::InvalidData => {\n        return Err(Box::new(e));\n    }\n    Err(e) => return Err(Box::new(e)),\n};","handlingStrategy":"try-catch","validationCode":"// No pre-call validation possible; kernel version mismatch surfaces at runtime.\n// Document the supported FreeBSD version range for your binary.","typeGuard":null,"tryCatchPattern":"match stream.peer_cred() {\n    Ok(cred) => { /* use cred */ },\n    Err(e) if e.kind() == io::ErrorKind::InvalidData => {\n        // xucred size or version mismatch on FreeBSD\n        return Err(e);\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Pin tokio and your build toolchain to a FreeBSD version matching the deployment kernel.","Document the supported FreeBSD major versions in your release notes.","Test peer_cred on every FreeBSD version you ship to."],"tags":["freebsd","unix-socket","peer-credentials","abi","io-error"],"backgroundTag":null,"analyzedSha":"625954f365727668cb02d04172b34f1149637728","analyzedAt":"2026-08-11T17:46:45.378Z","contentChangedAt":"2026-08-11T17:46:45.378Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}