{"record":{"id":"90868db6181b2dbf","repo":"junegunn/fzf","slug":"fzf-api-key-is-required-to-allow-remote-access","errorCode":null,"errorMessage":"FZF_API_KEY is required to allow remote access","messagePattern":"FZF_API_KEY is required to allow remote access","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/server.go","lineNumber":86,"sourceCode":"\t\treturn defaultListenAddr, fmt.Errorf(\"invalid listen address: %s\", address)\n\t}\n\tportStr := parts[len(parts)-1]\n\tport, err := strconv.Atoi(portStr)\n\tif err != nil || port < 0 || port > 65535 {\n\t\treturn defaultListenAddr, fmt.Errorf(\"invalid listen port: %s\", portStr)\n\t}\n\tif len(parts[0]) == 0 {\n\t\tparts[0] = \"localhost\"\n\t}\n\treturn listenAddress{parts[0], port, \"\"}, nil\n}\n\nfunc startHttpServer(address listenAddress, actionChannel chan []*action, getHandler func(getParams) string) (net.Listener, int, error) {\n\thost := address.host\n\tport := address.port\n\tapiKey := os.Getenv(\"FZF_API_KEY\")\n\tif !address.IsLocal() && len(apiKey) == 0 {\n\t\treturn nil, port, errors.New(\"FZF_API_KEY is required to allow remote access\")\n\t}\n\n\tvar listener net.Listener\n\tvar err error\n\tif len(address.sock) > 0 {\n\t\tif _, err := os.Stat(address.sock); err == nil {\n\t\t\t// Check if the socket is already in use\n\t\t\tif conn, err := net.Dial(\"unix\", address.sock); err == nil {\n\t\t\t\tconn.Close()\n\t\t\t\treturn nil, 0, fmt.Errorf(\"socket already in use: %s\", address.sock)\n\t\t\t}\n\t\t\tos.Remove(address.sock)\n\t\t}\n\t\tlistener, err = net.Listen(\"unix\", address.sock)\n\t\tif err != nil {\n\t\t\treturn nil, 0, fmt.Errorf(\"failed to listen on %s\", address.sock)\n\t\t}\n\t\tos.Chmod(address.sock, 0600)","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/junegunn/fzf/blob/bd4efa277b49ef34ca4025bff9b1a288e1980eff/src/server.go#L68-L104","documentation":"fzf's HTTP server (--listen) was given a non-local bind address, but no FZF_API_KEY environment variable is set. Because a remote listener lets any reachable client drive the selector, fzf refuses to start without an API key. This is a deliberate security guard, not a misconfiguration of the address itself.","triggerScenarios":"Running e.g. fzf --listen=0.0.0.0:6266 or --listen=192.168.1.5:6266 without FZF_API_KEY in the environment; only loopback hosts (localhost, 127.0.0.1, [::1]) are exempt via address.IsLocal().","commonSituations":"Running fzf in a container or on a server and wanting to control it from another machine; Docker port-forwarding setups where localhost inside the container is not the host's localhost.","solutions":["Set an API key: export FZF_API_KEY=$(head -c16 /dev/urandom | base64) before starting fzf","Or restrict the listener to loopback if remote access is not actually needed: --listen=127.0.0.0:6266 or plain --listen","Clients must then send the key via the X-api-key header on every request"],"exampleFix":"# before\nfzf --listen=0.0.0.0:6266\n# after\nexport FZF_API_KEY='s3cret-key'\nfzf --listen=0.0.0.0:6266\ncurl -H 'X-api-key: s3cret-key' http://host:6266/?q=query","handlingStrategy":"validation","validationCode":"# guard the listener start in shell\nhost=0.0.0.0; port=6266\nif [ \"$host\" != \"localhost\" ] && [ \"$host\" != \"127.0.0.1\" ] && [ -z \"${FZF_API_KEY:-}\" ]; then\n  echo 'refusing remote --listen without FZF_API_KEY' >&2; exit 1\nfi\nfzf --listen=\"$host:$port\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default to loopback listeners; widen only when remote control is truly required","Generate the key per session and distribute it to clients over a secret store, not the command line"],"tags":["fzf","server","security","authentication","network"],"backgroundTag":null,"analyzedSha":"bd4efa277b49ef34ca4025bff9b1a288e1980eff","analyzedAt":"2026-08-15T06:11:46.983Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}