{"record":{"id":"6a5d38224c554e51","repo":"hasura/graphql-engine","slug":"failed-to-create-a-symlink-from-q-to-q-w","errorCode":null,"errorMessage":"failed to create a symlink from %q to %q: %w","messagePattern":"failed to create a symlink from %q to %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/plugins/util.go","lineNumber":220,"sourceCode":"\t\t\t// If cloning the symlink fails on Windows because the user\n\t\t\t// does not have the required privileges, ignore the error and\n\t\t\t// fall back to copying the file contents.\n\t\t\t//\n\t\t\t// ERROR_PRIVILEGE_NOT_HELD is 1314 (0x522):\n\t\t\t// https://msdn.microsoft.com/en-us/library/windows/desktop/ms681385(v=vs.85).aspx\n\t\t\tvar lerr *os.LinkError\n\t\t\tif stderrors.As(err, &lerr); !stderrors.Is(lerr.Err, syscall.Errno(1314)) {\n\t\t\t\treturn errors.E(op, err)\n\t\t\t}\n\n\t\t\terr := copyFile(binary, dst, 0o755)\n\t\t\tif err != nil {\n\t\t\t\treturn errors.E(op, err)\n\t\t\t}\n\t\t} else {\n\t\t\treturn errors.E(\n\t\t\t\top,\n\t\t\t\tfmt.Errorf(\"failed to create a symlink from %q to %q: %w\", binary, dst, err),\n\t\t\t)\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// removeLink removes a symlink reference if exists.\nfunc removeLink(path string) error {\n\tvar op errors.Op = \"plugins.removeLink\"\n\n\tfi, err := os.Lstat(path)\n\tif stderrors.Is(err, fs.ErrNotExist) {\n\t\treturn nil\n\t} else if err != nil {\n\t\treturn errors.E(op, fmt.Errorf(\"failed to read the symlink in %q: %w\", path, err))\n\t}\n","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/plugins/util.go#L202-L238","documentation":"This error is thrown by the Go CLI plugin installer when it fails to create a symbolic link from the downloaded plugin binary into the plugin bin directory. The underlying OS error (permission denied, existing file, read-only filesystem, etc.) is wrapped with %w so the root cause is visible. It originates from createOrUpdateLink during installPlugin.","triggerScenarios":"Calling the plugin install flow when the symlink creation via os.Symlink fails: the destination path already exists as a non-link file, the bin directory is not writable, or on Windows the process lacks the SeCreateSymbolicLinkPrivilege privilege.","commonSituations":"Running `hasura plugin install` without admin rights on Windows (no symlink privilege), a leftover regular file at the destination from a previous manual install, or a read-only or non-existent plugins bin directory (~/.hasura/plugins/bin).","solutions":["Remove the stale destination file (e.g. rm ~/.hasura/plugins/bin/plugin.name) and retry the install.","On Windows, enable Developer Mode or run the terminal as Administrator so os.Symlink is permitted.","Verify the plugin bin directory exists and is writable: mkdir -p ~/.hasura/plugins/bin && check permissions.","Re-run the install with --version to force a clean install path."],"exampleFix":"// before\nrm ~/.hasura/plugins/bin/hasura-cli-plugin  # fails silently?\nhasura plugin install myplugin\n\n// after\n# ensure no regular file blocks the symlink\nrm -f ~/.hasura/plugins/bin/myplugin*\nhasura plugin install myplugin","handlingStrategy":"validation","validationCode":"// before install: ensure the destination is absent or a symlink\nbinDir := filepath.Join(home, \".hasura\", \"plugins\", \"bin\")\ndst := filepath.Join(binDir, pluginName)\nif fi, err := os.Lstat(dst); err == nil && fi.Mode()&os.ModeSymlink == 0 {\n    os.Remove(dst) // clear stale regular file\n}\nos.MkdirAll(binDir, 0o755)","typeGuard":null,"tryCatchPattern":"// Go: inspect the wrapped error chain\nerr := installPlugin(...)\nif err != nil {\n    var linkErr *os.LinkError\n    if errors.As(err, &linkErr) { /* symlink privilege/existence issue */ }\n}","preventionTips":["Keep the plugins bin directory writable by your user.","On Windows enable Developer Mode so unprivileged symlink creation works.","Never hand-copy binaries into the plugin bin directory; use the installer."],"tags":["go","filesystem","symlink","plugin-install","permissions"],"backgroundTag":"symlink-creation-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}