ErrLookup › Background articles › "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries

"Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries

"Invalid format", "must be in format 'platform:url'", "does not look like a valid id", "Expected format 'WIDTHxHEIGHT'" — these are invalid-argument-format errors, raised by CLI tools and libraries when an argument arrives with the wrong shape: a missing separator like a colon, an id pasted as a whole URL, a size string that will not parse, or a value matching no accepted pattern. You meet them in the first milliseconds of a command run, before any network call, when a flag value or positional argument fails the library's client-side shape check.

Distilled from 95 documented records across 17 repositories.

Background

This family sits at the outermost layer of a program: argument parsing and input validation. Before a CLI like mise, pnpm, or the OpenCLI adapters touches the network or the filesystem, it checks that each option value matches the shape it can actually work with. mise's generate tool-stub command splits platform specs on the first colon and rejects values that are neither 'platform:url' nor a detectable URL; pnpm's access grant/revoke splits the team argument on ':' to build a registry URL and rejects anything without one; OpenCLI's many adapters run regex checks (/^\d+$/, /^[A-Za-z0-9_-]+$/, /^[A-Z0-9]{1,32}$/, UUID patterns) over ids, handles, and timestamps. These checks exist to fail fast: a malformed train_no or security-id would only produce a garbage request against the upstream API, so the library refuses up front, usually with an ArgumentError or ValueError naming the offending value.

The dominant trigger across all 17 repositories is separator and shape confusion. Colon-delimited compound values are the clearest case: mise's 'platform:url' and 'platform:path' specs, pnpm's 'scope:team', ruflo's 'agent:<id>' or 'human:<id>' targets, and FD:DEST pairs in Codex's Linux sandbox all fail with a near-identical message when the colon is missing — typically because shell interpolation dropped one half, a value was copy-pasted without its prefix, or hand-built argv forgot the separator. A close second is pasting a whole URL where a bare identifier is expected: hotel ids, Zhihu answer ids, Twitter handles, BOSS security-ids, dianping shop ids, and list ids all get rejected when the caller passes 'https://...' instead of the extracted id. Some libraries deliberately accept both forms — OpenCLI's dianping and Kimi parsers extract ids from canonical URLs — but then enforce canonicality (https only, no fragments, the right host), so mobile or mirror links still fail.

Beyond separators and URLs, the family covers numeric and pattern-validated values: Trip.com hotel ids and X list ids must be pure digit strings, Coupang product ids need at least 6 digits, 12306 train_no must be 8-18 alphanumerics distinct from the public train code, Wayback timestamps must normalize to 4-14 digits, and limit/size arguments must be positive integers or 'WIDTHxHEIGHT' pairs. Note that behavior at the edges is library-specific: litellm's BFL mapper silently ignores size strings without an 'x' and only raises when an 'x' is present but the halves do not parse as integers, while matplotlib's axes_grid1 from_any raises on any unrecognized type outright, and its Grid rect check looks only at sequence length. Matplotlib also shows the family's variant of a subtle bug: unchecked string branches that push the real failure downstream to a different error (float() failing on '50 percent%').

The messages themselves follow a few recognizable templates: 'must be in format X' (mise, pnpm), 'does not look like a Y' (OpenCLI's 12306 train_no, dianping shop id), 'Expected format ...' (litellm), and rethrow wrappers that preserve an inner validator's message (OpenCLI's message-send and reaction-add commands prefix 'rethrown from ...'). Because most of these fire before any I/O, an error from this family almost always means the fix is entirely on the caller's side: reshape the argument, do not retry or look for a server problem.

Common causes

What usually fixes it

Documented occurrences

…and 75 more across the corpus — use search.

Honest provenance: generated on 2026-08-29 from AI-assisted analysis of the linked records. See how records are made.