core/commands: unexpected type %T, expected *"core/commands"

Error message

core/commands: unexpected type %T, expected *"core/commands".Command

What it means

This is the Encode method of the commands command-listing encoder: it expects the value handed to it to be a *Command from package core/commands. Any other value means the command's Run/encoder wiring returned the wrong result type. The message includes the actual dynamic type for diagnosis.

Source

Thrown at core/commands/commands.go:30

	"os"
	"slices"
	"strings"

	cmds "github.com/ipfs/go-ipfs-cmds"
)

type commandEncoder struct {
	w io.Writer
}

func (e *commandEncoder) Encode(v any) error {
	var (
		cmd *Command
		ok  bool
	)

	if cmd, ok = v.(*Command); !ok {
		return fmt.Errorf(`core/commands: unexpected type %T, expected *"core/commands".Command`, v)
	}

	for _, s := range cmdPathStrings(cmd, cmd.showOpts) {
		_, err := e.w.Write([]byte(s + "\n"))
		if err != nil {
			return err
		}
	}

	return nil
}

type Command struct {
	Name        string
	Subcommands []Command
	Options     []Option

	showOpts bool

View on GitHub (pinned to 329838acdf)

Solutions

Ensure the command's Run emits exactly a *core/commands.Command via the emitter (e.Emit(cmd))
If you changed the emitted type, update Encode to match the new type
Check for nil/mis-typed emitter values in custom wiring

Example fix

// before
return e.Emit(cmdStrings) // []string
// after
return e.Emit(cmd) // *Command

Defensive patterns

Strategy: type-guard

Validate before calling

cmd, ok := v.(*Command)
if !ok {
    return fmt.Errorf("encoder expected *Command, got %T", v)
}

Type guard

func asCommand(v interface{}) (*Command, bool) {
    c, ok := v.(*Command)
    return c, ok
}

Try / catch

if err := e.Emit(cmd); err != nil {
    if strings.Contains(err.Error(), "unexpected type") {
        log.Fatalf("command Run must emit *Command, got wrong type")
    }
    return err
}

Prevention

Keep the emitted value type in Run aligned with Encode's expectation
Run `go build ./core/commands/...` after changing command Run signatures
Add a unit test exercising the commands listing encoder

When it happens

Trigger: Invoking the `ipfs commands` listing command path with an encoder whose Run/Emitter produced something other than *core/commands.Command; changing the command's Run return type without updating the encoder.

Common situations: Modifying core/commands/commands.go Run function to emit a different structure; custom forks or embedded builds where the emitted value type drifted from the encoder's expectation.

Related errors

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