ipfs/kubo · error

failed to raise ulimit to minimum %d: set to %d

Error message

failed to raise ulimit to minimum %d: set to %d

What it means

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.

Source

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

		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)
	}

	return newLimit > 0, newLimit, err
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Raise the hard limit for the daemon user (limits.conf or systemd LimitNOFILE=) to at least 2048, ideally 8192 or higher.
2. 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.
3. 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.

Example fix

// before
docker run ipfs/kubo   # default nofile hard limit 1024
// after
docker run --ulimit nofile=8192:8192 ipfs/kubo

const minFds = 2048
var r unix.Rlimit
if err := unix.Getrlimit(unix.RLIMIT_NOFILE, &r); err != nil { return err }
if uint64(r.Max) < minFds {
    return fmt.Errorf("hard nofile limit %d below required %d; fix environment before starting", r.Max, minFds)
}

changed, newLimit, err := util.ManageFdLimit()
if err != nil && strings.Contains(err.Error(), "failed to raise ulimit to minimum") {
    return fmt.Errorf("environment unsuitable for daemon (need >=2048 fds): %w", err)
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• error setting ulimit without hard limit: %w
• failed to raise ulimit to IPFS_FD_MAX (%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/ae39e563674f371a. Report an issue: GitHub.