{"record":{"id":"2c7bc5576d220a79","repo":"mastra-ai/mastra","slug":"malformed-header","errorCode":"MALFORMED_HEADER","errorMessage":"MALFORMED_HEADER: Header must use \"Key: Value\" format","messagePattern":"MALFORMED_HEADER: Header must use \"Key: Value\" format","errorType":"error_code","errorClass":"ApiCliError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/api/headers.ts","lineNumber":9,"sourceCode":"import { ApiCliError } from './errors.js';\n\nexport function parseHeaders(values: string[]): Record<string, string> {\n  const headers: Record<string, string> = {};\n\n  for (const value of values) {\n    const separatorIndex = value.indexOf(':');\n    if (separatorIndex <= 0) {\n      throw new ApiCliError('MALFORMED_HEADER', 'Header must use \"Key: Value\" format', { header: value });\n    }\n\n    const key = value.slice(0, separatorIndex).trim();\n    const headerValue = value.slice(separatorIndex + 1).trim();\n\n    if (!key || !headerValue) {\n      throw new ApiCliError('MALFORMED_HEADER', 'Header must use \"Key: Value\" format', { header: value });\n    }\n\n    headers[key] = headerValue;\n  }\n\n  return headers;\n}\n","sourceCodeStart":1,"sourceCodeEnd":24,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/api/headers.ts#L1-L24","documentation":"parseHeaders converts repeated `--header`/`-H` CLI strings into a Record. Any value lacking a ':' separator (or where ':' is the first character, so the key is empty) is rejected with ApiCliError('MALFORMED_HEADER', 'Header must use \"Key: Value\" format'). It enforces the strict Key: Value convention early instead of producing silently broken HTTP headers.","triggerScenarios":"Passing a header string without a colon (e.g. `--header Authorization`) or starting with a colon (e.g. `--header :value`) to any CLI api command that accepts custom headers.","commonSituations":"Users accustomed to curl typing `-H \"Authorization Bearer x\"` (space instead of colon); quoting mistakes in shell scripts that swallow the colon; forgetting that curl's shorthand `-H \"key\"` sets an empty-valued header, which this parser does not allow.","solutions":["Rewrite the header using an explicit colon separator: `--header \"Key: Value\"`.","If a value itself contains a colon, only the first colon splits key/value, so quote the whole argument: `--header \"X-Signature: a:b:c\"`.","Check for shell quoting issues — run with the header in double quotes so the colon is not stripped.","Trim stray whitespace; keys and values are trimmed after the split, but the colon must still be present."],"exampleFix":"// before\nmastra api list-agents --header \"Authorization Bearer abc\"\n// after\nmastra api list-agents --header \"Authorization: Bearer abc\"","handlingStrategy":"validation","validationCode":"function isValidHeaderArg(v: string): boolean {\n  const i = v.indexOf(':');\n  return i > 0 && v.slice(0, i).trim().length > 0 && v.slice(i + 1).trim().length > 0;\n}\n// headers.every(isValidHeaderArg) before invoking","typeGuard":null,"tryCatchPattern":"try {\n  const headers = parseHeaders(rawHeaderArgs);\n} catch (e) {\n  if (e instanceof ApiCliError && e.code === 'MALFORMED_HEADER') {\n    console.error(`Fix header format (Key: Value): ${e.details.header}`);\n  } else {\n    throw e;\n  }\n}","preventionTips":["Always pass headers as `--header \"Key: Value\"` with a colon, quoting the whole argument in shell.","Remember only the first colon splits key/value, so values containing colons are fine when quoted.","Do not rely on curl-style shorthand `-H key` — this parser requires an explicit value.","Lint shell scripts for header arguments missing a colon."],"tags":["cli","http-headers","input-validation"],"backgroundTag":"malformed-http-header","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}