What causes "Illegal header name %s." in google/tsunami-security-scanner?

Print the offending name and check it against legal token characters (alphanumerics plus typical token punctuation like - _ .)

google/tsunami-security-scanner · error · ValueError

Illegal header name .

Error message

Illegal header name %s.

What it means

When canonicalize is enabled, add_header validates the header name against HEADER_NAME_MATCHER (a regex over legal RFC-style token characters). If the name contains characters outside that set, ValueError('Illegal header name ...') is raised before any header is stored.

Solutions

Print the offending name and check it against legal token characters (alphanumerics plus typical token punctuation like - _ .)
Split any 'Name: value' string into separate name and value arguments
Sanitize or reject header names from untrusted sources before calling add_header
Pass canonicalize=False only if you are certain the name is already canonical

Example fix

// before
builder.add_header(name_from_input, 'v')  # may contain ' ' or ':'
// after
import re
if re.fullmatch(r'[A-Za-z0-9-]+', name_from_input):
  builder.add_header(name_from_input, 'v')

Defensive patterns

Strategy: validation

Validate before calling

import re
LEGAL_NAME = re.compile(r'^[A-Za-z0-9-]+$')
def can_add(name):
    return bool(LEGAL_NAME.fullmatch(name))

Try / catch

try:
    builder.add_header(name, value)
except ValueError as e:
    logging.warning('Rejected header %r: %s', name, e)

Prevention

Split 'Name: value' strings before passing them to add_header
Whitelist allowed header names when sourced from user input
Never build header names by concatenating arbitrary strings

When it happens

Trigger: add_header('X Foo', 'v') (space), add_header('X-Foo:', 'v') (colon), or a name built by string concatenation that includes a newline, non-ASCII characters, or punctuation not allowed in header tokens.

Common situations: Building header names dynamically from user input or data-driven configs; typos like 'Content Type'; accidentally passing 'Name: value' as a single name string (common when copying curl headers).

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of google/tsunami-security-scanner@363ba87b35 (2026-09-13). Data as JSON: /api/errors/103b05b7b9b3948c. Report an issue: GitHub.

Appendix: source

Thrown at plugin_server/py/common/net/http/http_headers.py:102

    Returns:
      The builder object.

    Raises:
      ValueError: If name or value is None. If header name or value pair does
      not comply with standards.
    """
    if name is None:
      raise ValueError('Name cannot be None.')
    if value is None:
      raise ValueError('Value cannot be None.')
    if canonicalize:
      name = self._canonicalize_header_name(name, value)
    self.http_headers.raw_headers[name].append(value)
    return self

  def _canonicalize_header_name(self, name, value) -> str:
    if not self._is_legal_header_name(name):
      raise ValueError('Illegal header name %s.' % name)
    if not self._is_legal_header_value(value):
      raise ValueError('Illegal header value %s.' % value)
    return _canonicalize(name)

  def _is_legal_header_name(self, name: str) -> bool:
    return bool(re.fullmatch(self.HEADER_NAME_MATCHER, name))

  def _is_legal_header_value(self, value: str) -> bool:
    return bool(re.fullmatch(self.HEADER_VALUE_MATCHER, value))


def _canonicalize(header_name: str) -> str:
  """Normalize header field name.

  Args:
    header_name: An HTTP header field name.

  Returns:

View on GitHub (pinned to 363ba87b35)