What causes "error setting: ulimit: %w" in ipfs/kubo?

Inspect the wrapped error with errors.Is/As (e.g. syscall.EINVAL) to determine the OS-level cause.

error setting: ulimit: %w

Error message

error setting: ulimit: %w

What it means

The default branch of ManageFdLimit's error switch: setLimit returned an error other than nil or syscall.EPERM while raising the file-descriptor limit. The error only appears on platforms where supportsFDManagement is true; on Linux an error in the same path is returned unwrapped earlier, so this branch primarily covers platforms whose setLimit returns arbitrary syscall errors.

Source

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

		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

Inspect the wrapped error with errors.Is/As (e.g. syscall.EINVAL) to determine the OS-level cause.
Check that IPFS_FD_MAX is a sane number below fs.nr_open (`sysctl fs.nr_open`).
Verify the platform actually supports FD management (supportsFDManagement) and that the failure is not a sandbox/seccomp policy blocking setrlimit.

Example fix

// before
err = fmt.Errorf("error setting: ulimit: %w", err) // opaque errno
// after (caller diagnosis)
var errno syscall.Errno
if errors.As(err, &errno) {
    log.Warnf("setrlimit failed: %v", errno)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check the value about to be set
want := uint64(8192)
if v := os.Getenv("IPFS_FD_MAX"); v != "" {
    w, err := strconv.ParseUint(v, 10, 64)
    if err != nil || w == 0 || w > 1<<40 {
        log.Warnf("invalid IPFS_FD_MAX %q", v)
    }
}

Type guard

func isErrno(err error) (syscall.Errno, bool) {
    var e syscall.Errno
    if errors.As(err, &e) { return e, true }
    return 0, false
}

Try / catch

changed, newLimit, err := util.ManageFdLimit()
if err != nil {
    var errno syscall.Errno
    if errors.As(err, &errno) {
        switch errno {
        case syscall.EINVAL:
            log.Warnf("setrlimit EINVAL: value above fs.nr_open? err=%v", err)
        default:
            log.Warnf("setrlimit failed (%v), continuing", err)
        }
    }
}

Prevention

Keep IPFS_FD_MAX below the kernel fs.nr_open ceiling on Linux-like platforms
Treat errors from ManageFdLimit as advisory (match on wrapped errno) since a non-EPERM errno may be environmental
Log the wrapped cause rather than the outer message when triaging; the errno is the actionable part

When it happens

Trigger: ManageFdLimit() where setLimit(targetLimit, targetLimit) returns any non-nil, non-EPERM error, e.g. EINVAL from an invalid rlimit value or EPERM surfaced as a wrapped error rather than the bare syscall value.

Common situations: Exotic or restricted kernels/sandboxes rejecting setrlimit; values above the kernel's fs.nr_open on Linux-like builds; a wrapped EPERM that fails the errors.Is-style switch, sending an ordinary permission failure into the default branch.

Related errors

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