ipfs/kubo · error

unsupported file type '%s'

Error message

unsupported file type '%s'

What it means

The client/rpc Get helper resolves a UnixFS entry via the ls/stat RPC and materializes it as a files.Node locally. When the reported stat.Type is none of file/directory/symlink, it has no local representation and returns this error, embedding the unexpected type. Typically the type string comes from a newer daemon exposing a type this client version does not understand.

Source

Thrown at client/rpc/apifile.go:61

	mode, err := stringToFileMode(stat.Mode)
	if err != nil {
		return nil, err
	}

	var modTime time.Time
	if stat.Mtime != 0 {
		modTime = time.Unix(stat.Mtime, int64(stat.MtimeNsecs)).UTC()
	}

	switch stat.Type {
	case "file":
		return api.getFile(ctx, p, stat.Size, mode, modTime)
	case "directory":
		return api.getDir(ctx, p, stat.Size, mode, modTime)
	case "symlink":
		return api.getSymlink(ctx, p, modTime)
	default:
		return nil, fmt.Errorf("unsupported file type '%s'", stat.Type)
	}
}

type apiFile struct {
	ctx  context.Context
	core *HttpApi
	size int64
	path path.Path

	mode  os.FileMode
	mtime time.Time

	r  *Response
	at int64
}

func (f *apiFile) reset() error {
	if f.r != nil {

View on GitHub (pinned to 329838acdf)

Solutions

1. Upgrade client/rpc (and kubo) on both sides so daemon and client versions match
2. Check the type string with `ipfs files stat` or `ipfs ls` to see what the entry actually is
3. If it is a HAMT directory, access its contents via the normal directory listing path rather than fetching the shard node directly
4. Handle the error by falling back to `ipfs get`/`dag export` for unknown types

stat, err := api.Object().Stat(ctx, p) // or files stat
if err == nil {
    t := stat.Type
    if t != "file" && t != "directory" && t != "symlink" {
        return fmt.Errorf("client cannot handle type %q; upgrade client/rpc", t)
    }
}

func knownUnixfsType(t string) bool {
    switch t { case "file", "directory", "symlink": return true }
    return false
}

node, err := api.Unixfs().Get(ctx, p)
if err != nil && strings.Contains(err.Error(), "unsupported file type") {
    // fall back to raw fetch
    return api.Dag().Get(ctx, p)
}

When it happens

Trigger: Calling UnixfsAPI.Get (or the ipfsGet path) on a path whose stat.Type is not 'file', 'directory', or 'symlink' — e.g. an empty/different type string, a newer daemon reporting raw/hamt-shard differently, or a server returning an unexpected RPC shape.

Common situations: Version mismatch: new daemon (new UnixFS type rendering) with an old go client; fetching MFS entries that are UnixFS HAMT shards rendered unexpectedly; hand-rolled proxies that alter the ls RPC response.

Related errors

• file type %d not supported
• ipfs api address could not be found
• unexpected redirect
• cannot parse mode %s: %s
• ls returned more objects than expected (%d)

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