ipfs/kubo · warning

failed to raise ulimit to IPFS_FD_MAX (%d): set to %d

Error message

failed to raise ulimit to IPFS_FD_MAX (%d): set to %d

What it means

After an EPERM fallback that raises only the soft limit, ManageFdLimit checks whether the achieved limit met the user's explicit IPFS_FD_MAX. If the hard limit capped it lower, this error reports the requested versus achieved value. It signals the user-requested file-descriptor count could not be honored, not a hard failure of the setrlimit call itself.

Source

Thrown at cmd/ipfs/util/ulimit.go:93

	case syscall.EPERM:
		// lower limit if necessary.
		if targetLimit > hard {
			targetLimit = hard
		}

		// the process does not have permission so we should only
		// set the soft value
		err = setLimit(targetLimit, hard)
		if err != nil {
			err = fmt.Errorf("error setting ulimit without hard limit: %w", err)
			break
		}
		newLimit = targetLimit

		// Warn on lowered limit.

		if newLimit < userLimit {
			err = fmt.Errorf(
				"failed to raise ulimit to IPFS_FD_MAX (%d): set to %d",
				userLimit,
				newLimit,
			)
			break
		}

		if userLimit == 0 && newLimit < minFds {
			err = fmt.Errorf(
				"failed to raise ulimit to minimum %d: set to %d",
				minFds,
				newLimit,
			)
			break
		}
	default:
		err = fmt.Errorf("error setting: ulimit: %w", err)
	}

View on GitHub (pinned to 329838acdf)

Solutions

1. Raise the hard limit for the daemon user (`ulimit -Hn`, /etc/security/limits.conf, or systemd LimitNOFILE=hard) so it is >= IPFS_FD_MAX.
2. Run the daemon as root or with CAP_SYS_RESOURCE capability, which allows raising limits up to the kernel max (fs.nr_open).
3. Lower IPFS_FD_MAX to match the existing hard limit so the request and outcome agree.

Example fix

// before (systemd unit)
# no LimitNOFILE, IPFS_FD_MAX=65536
// after (systemd unit)
[Service]
LimitNOFILE=65536
Environment=IPFS_FD_MAX=65536

hard, err := getHardNoFileLimit() // via Getrlimit(RLIMIT_NOFILE)
if err != nil { return err }
if v := os.Getenv("IPFS_FD_MAX"); v != "" {
    want, _ := strconv.ParseUint(v, 10, 64)
    if want > hard {
        log.Warnf("IPFS_FD_MAX=%d exceeds hard limit %d; raise LimitNOFILE first", want, hard)
    }
}

changed, newLimit, err := util.ManageFdLimit()
if err != nil && strings.Contains(err.Error(), "failed to raise ulimit to IPFS_FD_MAX") {
    log.Warnf("continuing below requested IPFS_FD_MAX: %v", err)
}

When it happens

Trigger: ManageFdLimit() with IPFS_FD_MAX set to N, the initial setLimit(N, N) hits EPERM, the soft-only fallback succeeds but targetLimit was clamped to the hard limit, and newLimit < N.

Common situations: Operator sets IPFS_FD_MAX=65536 in an environment where the hard limit is only 4096 (default systemd or shell limits); production daemons expecting high connection counts on hosts with restrictive login limits.

Related errors

• error setting ulimit without hard limit: %w
• failed to raise ulimit to minimum %d: set to %d
• error setting: ulimit: %w
• invalid rlimits
• assets: could load Asset '%s': %s

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/6542913f4e3932b5. Report an issue: GitHub.