{"record":{"id":"ae39e563674f371a","repo":"ipfs/kubo","slug":"failed-to-raise-ulimit-to-minimum-d-set-to-d","errorCode":null,"errorMessage":"failed to raise ulimit to minimum %d: set to %d","messagePattern":"failed to raise ulimit to minimum (.+?): set to (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/ipfs/util/ulimit.go","lineNumber":102,"sourceCode":"\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\",\n\t\t\t\tminFds,\n\t\t\t\tnewLimit,\n\t\t\t)\n\t\t\tbreak\n\t\t}\n\tdefault:\n\t\terr = fmt.Errorf(\"error setting: ulimit: %w\", err)\n\t}\n\n\treturn newLimit > 0, newLimit, err\n}\n","sourceCodeStart":84,"sourceCodeEnd":115,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/util/ulimit.go#L84-L115","documentation":"When no explicit IPFS_FD_MAX is set (userLimit == 0), ManageFdLimit targets the default of 8192 and treats 2048 (minFds) as the minimum acceptable file-descriptor count. If the EPERM fallback could only raise the soft limit below 2048, this error reports the minimum and the achieved value. It flags environments too restricted for kubo's expected concurrency.","triggerScenarios":"ManageFdLimit() with IPFS_FD_MAX unset, the initial setLimit(8192, 8192) returns EPERM, the soft-only fallback clamps targetLimit to the hard limit, and that clamped value is below 2048.","commonSituations":"Minimal Docker containers or CI runners with hard nofile limits like 1024; shared hosting or restricted shells where ulimit -Hn is very low; older systemd defaults (LimitNOFILE=1024).","solutions":["Raise the hard limit for the daemon user (limits.conf or systemd LimitNOFILE=) to at least 2048, ideally 8192 or higher.","Set IPFS_FD_MAX explicitly to a value at or below the current hard limit so the intent is recorded and the target clamps sensibly.","Move the daemon to an environment (container config, VM, host) that permits at least 2048 open file descriptors, since kubo needs them for swarm connections."],"exampleFix":"// before\ndocker run ipfs/kubo   # default nofile hard limit 1024\n// after\ndocker run --ulimit nofile=8192:8192 ipfs/kubo","handlingStrategy":"validation","validationCode":"const minFds = 2048\nvar r unix.Rlimit\nif err := unix.Getrlimit(unix.RLIMIT_NOFILE, &r); err != nil { return err }\nif uint64(r.Max) < minFds {\n    return fmt.Errorf(\"hard nofile limit %d below required %d; fix environment before starting\", r.Max, minFds)\n}","typeGuard":null,"tryCatchPattern":"changed, newLimit, err := util.ManageFdLimit()\nif err != nil && strings.Contains(err.Error(), \"failed to raise ulimit to minimum\") {\n    return fmt.Errorf(\"environment unsuitable for daemon (need >=2048 fds): %w\", err)\n}","preventionTips":["Always run in environments whose hard nofile limit is at least 2048 (prefer 8192+)","For Docker use --ulimit nofile=8192:8192; for systemd set LimitNOFILE=8192","Fail fast at deploy time with a preflight rlimit check rather than at daemon start"],"tags":["ulimit","file-descriptors","containers","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"}