ipfs/kubo · error

cannot parse mode %s: %s

Error message

cannot parse mode %s: %s

What it means

stringToFileMode parses a mode string (expected octal digits, e.g. '644' or '0755') returned with the file's stat into os.FileMode. If strconv.ParseUint(mode, 8, 32) fails — empty strings are handled, so this means non-octal or out-of-range characters — the error wraps the parse failure. It propagates out of Get when the daemon supplies a mode field the client cannot parse.

Source

Thrown at client/rpc/apifile.go:171

func (f *apiFile) Mode() os.FileMode {
	return f.mode
}

func (f *apiFile) ModTime() time.Time {
	return f.mtime
}

func (f *apiFile) Size() (int64, error) {
	return f.size, nil
}

func stringToFileMode(mode string) (os.FileMode, error) {
	if mode == "" {
		return 0, nil
	}
	mode64, err := strconv.ParseUint(mode, 8, 32)
	if err != nil {
		return 0, fmt.Errorf("cannot parse mode %s: %s", mode, err)
	}
	return os.FileMode(uint32(mode64)), nil
}

func (api *UnixfsAPI) getFile(ctx context.Context, p path.Path, size int64, mode os.FileMode, mtime time.Time) (files.Node, error) {
	f := &apiFile{
		ctx:   ctx,
		core:  api.core(),
		size:  size,
		path:  p,
		mode:  mode,
		mtime: mtime,
	}

	return f, f.reset()
}

type apiIter struct {

View on GitHub (pinned to 329838acdf)

Solutions

1. Ensure the daemon/proxy returns mode as octal digits (e.g. '644', not 'rw-r--r--')
2. Pin matching kubo versions on client and daemon
3. If you control the value, validate octal before sending: `strconv.ParseUint(m, 8, 32)`
4. The error already wraps the cause with %w — use errors.Is/As on the inner *strconv.NumError to diagnose

Example fix

// before
mode := "rw-r--r--" // symbolic, will fail
// after
mode := "0644" // octal digits

if _, err := strconv.ParseUint(modeStr, 8, 32); err != nil {
    return fmt.Errorf("mode %q must be octal digits", modeStr)
}

func isOctalMode(s string) bool {
    if s == "" { return true }
    _, err := strconv.ParseUint(s, 8, 32)
    return err == nil
}

node, err := api.Unixfs().Get(ctx, p)
if err != nil && strings.Contains(err.Error(), "cannot parse mode") {
    var numErr *strconv.NumError
    if errors.As(err, &numErr) { log.Printf("bad mode %q from server", numErr.Num) }
    // retry against an unmodified kubo daemon
}

When it happens

Trigger: Calling Get on an RPC daemon whose ls/stat response contains a malformed or non-octal mode string (e.g. 'rw-r--r--' symbolic instead of octal, or '999' with invalid octal digits); custom servers altering the field format.

Common situations: Proxies or re-implementations of /api/v0 that emit symbolic permission strings; cross-version drift in the ls RPC schema; tests/mocks with hand-written mode values.

Related errors

• ipfs api address could not be found
• unexpected redirect
• unsupported file type '%s'
• ls returned more objects than expected (%d)
• ls returned more links than expected (%d)

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