ipfs/kubo · error

unable to use %q (deprecated) and a custom %q at the same ti

Error message

unable to use %q (deprecated) and a custom %q at the same time

What it means

`ipfs block put` accepts the legacy, deprecated --format flag and the newer --cid-codec flag. Passing both simultaneously is ambiguous: --format suppresses cid-codec handling for legacy CIDv0 output. A custom (non-raw) --cid-codec together with --format cannot be reconciled, so the command refuses the combination.

Source

Thrown at core/commands/block.go:215

		}

		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)
			if file == nil {
				return errors.New("expected a file")
			}

			p, err := api.Block().Put(req.Context, file,
				options.Block.Hash(mhtval, mhlen),
				options.Block.CidCodec(cidCodec),
				options.Block.Format(format),
				options.Block.Pin(pin))

View on GitHub (pinned to 329838acdf)

Solutions

1. Drop --format and use only --cid-codec for new code
2. If legacy CIDv0 output is required, use only --format=v0 and remove --cid-codec (or leave it at default 'raw')
3. Update scripts: --format is deprecated and will eventually be removed

Example fix

// before
ipfs block put --format=v0 --cid-codec=dag-pb data.bin
// after
ipfs block put --cid-codec=dag-pb data.bin

// shell: reject scripts that set both flags
if [ -n "$FORMAT" ] && [ -n "$CIDCODEC" ] && [ "$CIDCODEC" != "raw" ]; then
  echo "use --cid-codec only; --format is deprecated" >&2; exit 1
fi

When it happens

Trigger: Run `ipfs block put --format=v0 --cid-codec=dag-pb data.bin` (or any cid-codec other than the default 'raw') — the format != "" branch sees cidCodec not in {"", "raw"} and errors.

Common situations: Older scripts using --format=v0 updated to also set --cid-codec; users migrating flags and leaving both in place; copy-pasted command lines from different documentation versions.

Related errors

• api flag specified but command cannot be run on the daemon
• unrecognized multihash function: %s
• missing option "mhlen"
• expected a file
• supernode routing was never fully implemented and has been r

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