{"record":{"id":"33597444a5c7bc56","repo":"ipfs/kubo","slug":"error-setting-ulimit-without-hard-limit-w","errorCode":null,"errorMessage":"error setting ulimit without hard limit: %w","messagePattern":"error setting ulimit without hard limit: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/ipfs/util/ulimit.go","lineNumber":85,"sourceCode":"\t// corresponding resource\n\t// the hard limit acts as a ceiling for the soft limit\n\t// an unprivileged process may only set its soft limit to a\n\t// value in the range from 0 up to the hard limit\n\terr = setLimit(targetLimit, targetLimit)\n\tswitch err {\n\tcase nil:\n\t\tnewLimit = targetLimit\n\tcase syscall.EPERM:\n\t\t// lower limit if necessary.\n\t\tif targetLimit > hard {\n\t\t\ttargetLimit = hard\n\t\t}\n\n\t\t// the process does not have permission so we should only\n\t\t// set the soft value\n\t\terr = setLimit(targetLimit, hard)\n\t\tif err != nil {\n\t\t\terr = fmt.Errorf(\"error setting ulimit without hard limit: %w\", err)\n\t\t\tbreak\n\t\t}\n\t\tnewLimit = targetLimit\n\n\t\t// Warn on lowered limit.\n\n\t\tif newLimit < userLimit {\n\t\t\terr = fmt.Errorf(\n\t\t\t\t\"failed to raise ulimit to IPFS_FD_MAX (%d): set to %d\",\n\t\t\t\tuserLimit,\n\t\t\t\tnewLimit,\n\t\t\t)\n\t\t\tbreak\n\t\t}\n\n\t\tif userLimit == 0 && newLimit < minFds {\n\t\t\terr = fmt.Errorf(\n\t\t\t\t\"failed to raise ulimit to minimum %d: set to %d\",","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/util/ulimit.go#L67-L103","documentation":"ManageFdLimit tried to raise the process file-descriptor limit. After the first attempt to set both soft and hard limits failed with EPERM (no privilege), it fell back to raising only the soft limit while keeping the current hard limit, and that fallback call to setLimit also failed. The original OS error is wrapped, so inspect it with errors.Is/errors.As for the underlying cause.","triggerScenarios":"ManageFdLimit() when the soft limit is below the target (IPFS_FD_MAX or default 8192), the first setLimit(target, target) returns syscall.EPERM, and the second setLimit(targetLimit, hard) also returns an error (e.g. EPERM again because the soft limit exceeds the hard limit, or EINVAL).","commonSituations":"Running the daemon as an unprivileged user whose hard limit is lower than the requested IPFS_FD_MAX; container environments (Docker/Kubernetes) that lock rlimits via ulimits settings; misconfigured IPFS_FD_MAX set above the shell's hard limit (ulimit -Hn).","solutions":["Check the wrapped cause with errors.Is(err, syscall.EPERM) and lower IPFS_FD_MAX to at or below the hard limit (see `ulimit -Hn`).","Raise the daemon user's hard nofile limit via /etc/security/limits.conf or systemd LimitNOFILE=, then start the daemon under that environment.","In containers, configure the runtime's nofile ulimits (docker run --ulimit nofile=..., or Kubernetes securityContext) to permit the desired value."],"exampleFix":"// before\nos.Setenv(\"IPFS_FD_MAX\", \"1000000\") // above hard limit\n// after\n// shell: ulimit -Hn  ->  e.g. 1048576\nos.Setenv(\"IPFS_FD_MAX\", \"1048576\") // at or below the hard limit","handlingStrategy":"fallback","validationCode":"var r unix.Rlimit\nif err := unix.Getrlimit(unix.RLIMIT_NOFILE, &r); err != nil { return err }\nwant := uint64(8192)\nif v := os.Getenv(\"IPFS_FD_MAX\"); v != \"\" { want, _ = strconv.ParseUint(v, 10, 64) }\nif want > r.Max {\n    log.Warnf(\"IPFS_FD_MAX (%d) exceeds hard limit (%d); clamping\", want, r.Max)\n}","typeGuard":"func saneRLimit(cur, max int64) bool { return cur >= 0 && max >= 0 && cur <= max }","tryCatchPattern":"changed, newLimit, err := util.ManageFdLimit()\nif err != nil {\n    var errno syscall.Errno\n    if errors.As(err, &errno) && errors.Is(errno, syscall.EPERM) {\n        log.Warnf(\"ulimit raise denied (EPERM), continuing with %d fds\", newLimit)\n    } else {\n        return fmt.Errorf(\"fd limit: %w\", err)\n    }\n}","preventionTips":["Check `ulimit -Hn` before setting IPFS_FD_MAX and keep it at or below the hard limit","In systemd units set LimitNOFILE= explicitly rather than relying on defaults","Configure container nofile ulimits at deployment time (docker --ulimit, Kubernetes values)"],"tags":["ulimit","file-descriptors","permissions","go"],"backgroundTag":"ulimit-raise-denied","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}