{"record":{"id":"bb5aed3e4647fb4a","repo":"microsoft/typescript-go","slug":"unsupported-fanotify-metadata-version-d","errorCode":null,"errorMessage":"unsupported fanotify metadata version: %d","messagePattern":"unsupported fanotify metadata version: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/fswatch/fanotify_linux.go","lineNumber":401,"sourceCode":"\n\tfor {\n\t\tn, err := unix.Read(b.fanotifyFD, buf)\n\t\tif err != nil {\n\t\t\tif errors.Is(err, unix.EAGAIN) || errors.Is(err, unix.EWOULDBLOCK) {\n\t\t\t\tbreak\n\t\t\t}\n\t\t\treturn fmt.Errorf(\"Error reading from fanotify: %w\", err)\n\t\t}\n\t\tif n == 0 {\n\t\t\tbreak\n\t\t}\n\n\t\tmetaSize := int(unsafe.Sizeof(unix.FanotifyEventMetadata{}))\n\t\tdata := buf[:n]\n\t\tfor len(data) >= metaSize {\n\t\t\tmeta := (*unix.FanotifyEventMetadata)(unsafe.Pointer(&data[0]))\n\t\t\tif meta.Vers != unix.FANOTIFY_METADATA_VERSION {\n\t\t\t\treturn fmt.Errorf(\"unsupported fanotify metadata version: %d\", meta.Vers)\n\t\t\t}\n\t\t\teventLen := int(meta.Event_len)\n\t\t\tif eventLen < int(meta.Metadata_len) || eventLen > len(data) {\n\t\t\t\tbreak\n\t\t\t}\n\n\t\t\t// FID mode: fd should be FAN_NOFD, but close if somehow set.\n\t\t\tif meta.Fd >= 0 {\n\t\t\t\t_ = unix.Close(int(meta.Fd))\n\t\t\t}\n\n\t\t\tif meta.Mask&unix.FAN_Q_OVERFLOW != 0 {\n\t\t\t\tb.handleOverflow(watchersTouched)\n\t\t\t\tdata = data[eventLen:]\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\tinfoData := data[meta.Metadata_len:eventLen]","sourceCodeStart":383,"sourceCodeEnd":419,"githubUrl":"https://github.com/microsoft/typescript-go/blob/1bcfa18d79a3be41772223d5c05dfe4480e614ff/internal/fswatch/fanotify_linux.go#L383-L419","documentation":"A parsed fanotify event metadata record carries a version field that does not match FANOTIFY_METADATA_VERSION compiled into this binary. The kernel and userspace disagree on the ABI of the notification record, so the buffer cannot be parsed safely and the backend aborts event processing.","triggerScenarios":"Running a binary built against one kernel header set on a kernel with a different fanotify metadata ABI (essentially only possible across very old/mismatched kernels or patched kernels); golang.org/x/sys/unix constants out of sync with the running kernel.","commonSituations":"Extremely rare in practice; would surface after OS downgrades to pre-FID fanotify, custom/vendor kernels, or running under syscall-shimming VMs that synthesize fanotify responses.","solutions":["Rebuild/update the binary so its x/sys/unix fanotify constants match the running kernel (>= 5.1 with FID reporting)","Run on a mainstream, current kernel where the fanotify ABI matches FANOTIFY_METADATA_VERSION","Fall back to the inotify backend for that environment"],"exampleFix":"// before\nw, err := fswatch.Default().WatchDirectory(dir, cb) // metadata version mismatch on old custom kernel\n\n// after: pin a backend with a stable ABI on this host\nw, err := fswatch.Inotify().WatchDirectory(dir, cb, fswatch.WithRecursive())","handlingStrategy":"fallback","validationCode":"// Report the ABI mismatch precisely instead of failing vaguely.\nfunc fanotifyAbiOK() error {\n    var u unix.Utsname\n    if unix.Uname(&u) == nil {\n        v := strings.TrimPrefix(unix.ByteSliceToString(u.Release[:]), \"\")\n        if semverLess(v, \"5.1.0\") {\n            return fmt.Errorf(\"kernel %s lacks FID fanotify ABI\", v)\n        }\n    }\n    return nil\n}","typeGuard":"func isMetadataVersionMismatch(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"unsupported fanotify metadata version\")\n}","tryCatchPattern":"w, err := fswatch.Default().WatchDirectory(dir, cb, opts...)\nif err != nil && isMetadataVersionMismatch(err) {\n    // Kernel/binary ABI mismatch: switch to a backend with a stable ABI.\n    w, err = fswatch.Inotify().WatchDirectory(dir, cb, opts...)\n}\nif err != nil { return err }","preventionTips":["Build against a current golang.org/x/sys/unix and target kernels >= 5.1 (FID reporting)","Refuse to run fanotify backends on vendor/downgraded kernels; select inotify at startup","Report persistent metadata-version failures upstream with `uname -r` and the binary build info"],"tags":["linux","fanotify","kernel-abi","version-mismatch","fswatch"],"backgroundTag":null,"analyzedSha":"1bcfa18d79a3be41772223d5c05dfe4480e614ff","analyzedAt":"2026-08-16T02:12:00.115Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}