What causes "invalid format string: %q" in ipfs/kubo?

Add at least one printf-style directive to --format, e.g. --format='%s' or --format=%v-%c

invalid format string: %q

Error message

invalid format string: %q

What it means

`ipfs cid format` rejects a format string that contains no '%' directive. The command validates that the user-supplied --format actually interpolates CID components before building cidFormatOpts; a string with no % placeholder would render constant output, so it is treated as invalid.

Source

Thrown at core/commands/cid.go:75

	Arguments: []cmds.Argument{
		cmds.StringArg("cid", true, true, "CIDs to format.").EnableStdin(),
	},
	Options: []cmds.Option{
		cmds.StringOption(cidFormatOptionName, "Printf style format string.").WithDefault("%s"),
		cmds.StringOption(cidToVersionOptionName, "CID version to convert to."),
		cmds.StringOption(cidCodecOptionName, "CID multicodec to convert to."),
		cmds.StringOption(cidMultibaseOptionName, "Multibase to display CID in."),
	},
	Run: func(req *cmds.Request, resp cmds.ResponseEmitter, env cmds.Environment) error {
		fmtStr, _ := req.Options[cidFormatOptionName].(string)
		verStr, _ := req.Options[cidToVersionOptionName].(string)
		codecStr, _ := req.Options[cidCodecOptionName].(string)
		baseStr, _ := req.Options[cidMultibaseOptionName].(string)

		opts := cidFormatOpts{}

		if strings.IndexByte(fmtStr, '%') == -1 {
			return fmt.Errorf("invalid format string: %q", fmtStr)
		}
		opts.fmtStr = fmtStr

		if codecStr != "" {
			var codec mc.Code
			err := codec.Set(codecStr)
			if err != nil {
				return err
			}
			opts.newCodec = uint64(codec)
		} // otherwise, leave it as 0 (not a valid IPLD codec)

		switch verStr {
		case "":
			if baseStr != "" {
				opts.verConv = toCidV1
			}
		case "0":

View on GitHub (pinned to 329838acdf)

Solutions

Add at least one printf-style directive to --format, e.g. --format='%s' or --format=%v-%c
Check the formatted string comes from the right variable and wasn't shell-expanded away (quote % in shells)

Example fix

// before
ipfs cid format --format=cid <cid>
// after
ipfs cid format --format=%s <cid>

Defensive patterns

Strategy: validation

Validate before calling

if !strings.Contains(f, "%") {
    return fmt.Errorf("format string must contain a %% directive: %q", f)
}

Prevention

Always include a printf directive like %s in --format
Quote the format string in shells so % is not consumed
Test new format strings on a known CID before scripting them

When it happens

Trigger: Running `ipfs cid format --format=<string>` (or `cidFmt` option programmatically) where fmtStr contains no '%' byte, e.g. `--format=cid` instead of `--format=%s`.

Common situations: Users passing a plain label or forgetting printf-style placeholders; scripts that build the format string dynamically and drop the %; confusion with non-printf format syntaxes.

Related errors

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