{"record":{"id":"b275e145d774c289","repo":"v2rayA/v2rayA","slug":"failed-to-start-tinytun-w","errorCode":null,"errorMessage":"failed to start tinytun: %w","messagePattern":"failed to start tinytun: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"service/kernel/v2ray/tinytun_enabled.go","lineNumber":839,"sourceCode":"\tsetting := configure.GetSettingNotNil()\n\n\tcmdArgs := []string{\"run\", \"--config\", configPath}\n\tcmd := exec.CommandContext(ctx, binPath, cmdArgs...)\n\tcmd.Stdout = tinytunLineWriter{}\n\tcmd.Stderr = tinytunLineWriter{}\n\n\t// On Linux, when the user selects the eBPF process-exclusion backend,\n\t// set TINYTUN_EBPF_OBJECT so TinyTun loads the eBPF programs from the\n\t// standard installation path (/usr/lib/tinytun/tinytun-ebpf.o).\n\tif runtime.GOOS == \"linux\" && setting.TunProcessBackend == \"ebpf\" {\n\t\tif os.Getenv(\"TINYTUN_EBPF_OBJECT\") == \"\" {\n\t\t\tcmd.Env = append(os.Environ(), \"TINYTUN_EBPF_OBJECT=/usr/lib/tinytun/tinytun-ebpf.o\")\n\t\t}\n\t}\n\n\tif err = cmd.Start(); err != nil {\n\t\tcancel()\n\t\treturn fmt.Errorf(\"failed to start tinytun: %w\", err)\n\t}\n\n\tdoneCh := make(chan struct{})\n\n\ttinyTunState.mu.Lock()\n\tif tinyTunState.cancel != nil {\n\t\ttinyTunState.cancel()\n\t}\n\t// Set the new cancel function before resetting the stopping flag so that\n\t// any concurrent stopTinyTun that reads stopping==0 already sees the new\n\t// cancel and will correctly cancel the new process.\n\ttinyTunState.cancel = cancel\n\ttinyTunState.done = doneCh\n\tatomic.StoreInt32(&tinyTunState.stopping, 0)\n\ttinyTunState.mu.Unlock()\n\n\t// Monitor for unexpected exits: if TinyTun dies without its context being cancelled,\n\t// the proxy is in an inconsistent state and must be stopped.","sourceCodeStart":821,"sourceCodeEnd":857,"githubUrl":"https://github.com/v2rayA/v2rayA/blob/71e5442fc548c05680ee55eae943e6c0afe9ac51/service/kernel/v2ray/tinytun_enabled.go#L821-L857","documentation":"This error wraps the underlying error returned by exec.Cmd.Start() when the tinytun process (an eBPF-based TUN transparent-proxy helper) fails to launch. The library throws it because the external tinytun binary could not be spawned at all (binary missing, not executable, missing eBPF object file, or OS-level exec failure). The wrapped cause (%w) is in the message and must be inspected to know the real reason.","triggerScenarios":"startTinyTun builds an exec.Command for the tinytun binary (with env TINYTUN_EBPF_OBJECT=/usr/lib/tinytun/tinytun-ebpf.o when configured) and calls cmd.Start(); any non-nil error from Start (binary not found, exec format error, permission denied, missing TINYTUN_EBPF_OBJECT file check done before spawn) triggers this wrapper, after calling cancel() to unwind the context.","commonSituations":"Building with -tags tinytun on a system where the tinytun binary or /usr/lib/tinytun/tinytun-ebpf.o is absent; wrong architecture binary (exec format error); non-root user lacking permission to run eBPF tooling; PATH misconfigured in systemd service environments.","solutions":["Verify the tinytun binary exists and is executable (check GetTinyTunBinPath output and run it manually).","Confirm /usr/lib/tinytun/tinytun-ebpf.o exists or set TINYTUN_EBPF_OBJECT to the correct path.","Read the wrapped %w cause: ENOENT -> install binary, EACCES -> chmod/permissions, ENOEXEC -> wrong arch binary.","Run as root with eBPF/capabilities available (CAP_BPF/CAP_NET_ADMIN) since tinytun needs them.","Rebuild v2rayA with -tags tinytun matching your platform."],"exampleFix":"// before\ncmd.Env = append(os.Environ(), \"TINYTUN_EBPF_OBJECT=/usr/lib/tinytun/tinytun-ebpf.o\")\nif err = cmd.Start(); err != nil { ... }\n// after\nif _, err := os.Stat(tinytunBin); err != nil {\n\treturn fmt.Errorf(\"tinytun binary missing: %w\", err)\n}\nif _, err := os.Stat(ebpfObjectPath); err != nil {\n\treturn fmt.Errorf(\"eBPF object missing: %w\", err)\n}\ncmd.Env = append(os.Environ(), \"TINYTUN_EBPF_OBJECT=\"+ebpfObjectPath)","handlingStrategy":"try-catch","validationCode":"if !v2ray.IsTinyTunEnabled() { return errors.New(\"tinytun not compiled in\") }\nif _, err := os.Stat(\"/usr/lib/tinytun/tinytun-ebpf.o\"); err != nil { return err }","typeGuard":null,"tryCatchPattern":"if err := setupTransparentProxy(); err != nil {\n\tif strings.Contains(err.Error(), \"failed to start tinytun\") {\n\t\tlog.Warnf(\"tinytun start failed: %v — falling back to redirect mode\", err)\n\t}\n}","preventionTips":["Check IsTinyTunEnabled() and binary/eBPF-object existence before enabling tinytun mode.","Run with root/eBPF capabilities.","Verify binary architecture matches the host."],"tags":["process","exec","ebpf","transparent-proxy"],"backgroundTag":"process-start-failed","analyzedSha":"71e5442fc548c05680ee55eae943e6c0afe9ac51","analyzedAt":"2026-09-05T20:04:37.459Z","contentChangedAt":"2026-09-05T20:04:37.459Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}