mastra-ai/mastra · error · ApiCliError

MALFORMED_HEADER

MALFORMED_HEADER

Error message

MALFORMED_HEADER: Header must use "Key: Value" format

What it means

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.

Source

Thrown at packages/cli/src/commands/api/headers.ts:9

import { ApiCliError } from './errors.js';

export function parseHeaders(values: string[]): Record<string, string> {
  const headers: Record<string, string> = {};

  for (const value of values) {
    const separatorIndex = value.indexOf(':');
    if (separatorIndex <= 0) {
      throw new ApiCliError('MALFORMED_HEADER', 'Header must use "Key: Value" format', { header: value });
    }

    const key = value.slice(0, separatorIndex).trim();
    const headerValue = value.slice(separatorIndex + 1).trim();

    if (!key || !headerValue) {
      throw new ApiCliError('MALFORMED_HEADER', 'Header must use "Key: Value" format', { header: value });
    }

    headers[key] = headerValue;
  }

  return headers;
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Rewrite the header using an explicit colon separator: `--header "Key: Value"`.
2. 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"`.
3. Check for shell quoting issues — run with the header in double quotes so the colon is not stripped.
4. Trim stray whitespace; keys and values are trimmed after the split, but the colon must still be present.

Example fix

// before
mastra api list-agents --header "Authorization Bearer abc"
// after
mastra api list-agents --header "Authorization: Bearer abc"

function isValidHeaderArg(v: string): boolean {
  const i = v.indexOf(':');
  return i > 0 && v.slice(0, i).trim().length > 0 && v.slice(i + 1).trim().length > 0;
}
// headers.every(isValidHeaderArg) before invoking

try {
  const headers = parseHeaders(rawHeaderArgs);
} catch (e) {
  if (e instanceof ApiCliError && e.code === 'MALFORMED_HEADER') {
    console.error(`Fix header format (Key: Value): ${e.details.header}`);
  } else {
    throw e;
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• MISSING_INPUT
• INVALID_JSON
• The --empty and --template options can't be used together
• The --llm option can only be used with the default template
• The --llm-api-key option can only be used with the default t

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/2c7bc5576d220a79. Report an issue: GitHub.