ipfs/kubo · error

missing option "mhlen"

Error message

missing option "mhlen"

What it means

The --mhlen option is declared with a default of -1, so if the parsed option value is not an int the command treats the option as missing and fails. In practice this fires when the option type assertion fails, indicating an internal options-parsing inconsistency rather than normal user input.

Source

Thrown at core/commands/block.go:206

		cfg, err := nd.Repo.Config()
		if err != nil {
			return err
		}

		mhtype, _ := req.Options[mhtypeOptionName].(string)
		if mhtype == "" {
			mhtype = cfg.Import.HashFunction.WithDefault(config.DefaultHashFunction)
		}

		mhtval, ok := mh.Names[mhtype]
		if !ok {
			return fmt.Errorf("unrecognized multihash function: %s", mhtype)
		}

		mhlen, ok := req.Options[mhlenOptionName].(int)
		if !ok {
			return errors.New("missing option \"mhlen\"")
		}

		cidCodec, _ := req.Options[blockCidCodecOptionName].(string)
		format, _ := req.Options[blockFormatOptionName].(string) // deprecated

		// use of legacy 'format' needs to suppress 'cid-codec'
		if format != "" {
			if cidCodec != "" && cidCodec != "raw" {
				return fmt.Errorf("unable to use %q (deprecated) and a custom %q at the same time", blockFormatOptionName, blockCidCodecOptionName)
			}
			cidCodec = "" // makes it no-op
		}

		pin, _ := req.Options[pinOptionName].(bool)

		it := req.Files.Entries()
		for it.Next() {
			file := files.FileFromEntry(it)

View on GitHub (pinned to 329838acdf)

Solutions

1. Invoke the command via the normal CLI or /api/v0/ surface so options are parsed correctly
2. Omit --mhlen entirely (default -1 means use full hash length)
3. Fix the calling code to pass an int for the mhlen option

Example fix

// before
opts["mhlen"] = "32" // string breaks assertion
// after
opts["mhlen"] = 32   // int

// omit --mhlen or pass it as a plain integer
ipfs block put --mhlen 32 data.bin

When it happens

Trigger: req.Options[mhlenOptionName] is not an int after cmds option parsing — e.g. invoked through a code path that builds the options map manually with a string or float value for 'mhlen', bypassing normal CLI parsing.

Common situations: Programmatic invocation of the command Run function with hand-built options; RPC/API layer regression where option values arrive with unexpected types; forks that changed the option declaration.

Related errors

• unknown event type
• unrecognized multihash function: %s
• unable to use %q (deprecated) and a custom %q at the same ti
• expected a file
• compression level must be between 1 and 9

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