{"record":{"id":"10a076b1bed97fa2","repo":"cloudflare/cloudflared","slug":"service-installation-is-not-supported-on-this-oper","errorCode":null,"errorMessage":"service installation is not supported on this operating system","messagePattern":"service installation is not supported on this operating system","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cloudflared/generic_service.go","lineNumber":35,"sourceCode":"\t\tUsage: \"Manages the cloudflared system service (not supported on this operating system)\",\n\t\tSubcommands: []*cli.Command{\n\t\t\t{\n\t\t\t\tName:   \"install\",\n\t\t\t\tUsage:  \"Install cloudflared as a system service (not supported on this operating system)\",\n\t\t\t\tAction: cliutil.ConfiguredAction(installGenericService),\n\t\t\t},\n\t\t\t{\n\t\t\t\tName:   \"uninstall\",\n\t\t\t\tUsage:  \"Uninstall the cloudflared service (not supported on this operating system)\",\n\t\t\t\tAction: cliutil.ConfiguredAction(uninstallGenericService),\n\t\t\t},\n\t\t},\n\t})\n\tapp.Run(os.Args)\n}\n\nfunc installGenericService(c *cli.Context) error {\n\treturn fmt.Errorf(\"service installation is not supported on this operating system\")\n}\n\nfunc uninstallGenericService(c *cli.Context) error {\n\treturn fmt.Errorf(\"service uninstallation is not supported on this operating system\")\n}\n","sourceCodeStart":17,"sourceCodeEnd":41,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cmd/cloudflared/generic_service.go#L17-L41","documentation":"cloudflared's generic (fallback) service implementation is a stub: on platforms without native service support (not Windows, macOS, or Linux/systemd), `cloudflared service install` returns this error immediately. It indicates the requested operation is unsupported on the current OS, not that something is misconfigured.","triggerScenarios":"Running `cloudflared service install` (mapped to installGenericService) on an OS with no platform-specific service file — e.g. building/running the generic_service.go variant on FreeBSD, OpenBSD, Solaris, or an unsupported/unrecognized Linux init system.","commonSituations":"Running cloudflared inside minimal containers or on BSD variants expecting systemd-like service registration; using a from-source build tagged for the generic service path; calling the service install CLI command on an embedded device.","solutions":["Check the platform: service install is supported on Windows, macOS (launchd), and Linux (systemd/SysV). Use `cloudflared service install` only there.","On unsupported OS, run cloudflared as a plain foreground process (`cloudflared tunnel run ...`) and manage it with the OS-native supervisor (rc scripts, s6, supervisord, docker restart policies).","If on Linux but getting the stub, verify your binary was built with the linux service file (linux_service.go) and not the generic variant for your init system.","Consider running cloudflared in Docker with --restart unless-stopped as the supported containerized alternative."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// check platform support before calling service install\nfunc serviceInstallSupported() bool {\n\tswitch runtime.GOOS {\n\tcase \"windows\", \"darwin\", \"linux\":\n\t\treturn true\n\t}\n\treturn false\n}","typeGuard":"func isSupportedPlatform() bool { return runtime.GOOS == \"windows\" || runtime.GOOS == \"darwin\" || runtime.GOOS == \"linux\" }","tryCatchPattern":"if err := installService(); err != nil {\n\tif strings.Contains(err.Error(), \"not supported on this operating system\") {\n\t\t// fall back to foreground run / native supervisor\n\t}\n\treturn err\n}","preventionTips":["Gate service subcommands on GOOS/init-system detection in automation scripts.","On unsupported OS, provision cloudflared via a native supervisor unit instead.","Test service install on the exact target platform image before fleet rollout."],"tags":["service","unsupported-platform","cloudflared","cli"],"backgroundTag":"unsupported-platform","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}