FlowiseAI/Flowise · error · Error

Invalid header "${key}": key contains illegal characters

Error message

Invalid header "${key}": key contains illegal characters

What it means

Per-entry guard: each key must match RFC7230_TOKEN `/^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/`. Any character outside that set fails — colon, space, slash, equals, parens, non-ASCII, etc.

Source

Thrown at packages/components/src/headerValidation.ts:57

export function validateCustomHeaders(headers: Record<string, string>): void {
    if (!headers || typeof headers !== 'object') {
        throw new Error('Invalid headers: expected an object')
    }

    const entries = Object.entries(headers)
    if (entries.length > MAX_HEADERS) {
        throw new Error(`Invalid headers: too many entries (max ${MAX_HEADERS})`)
    }

    for (const [key, value] of entries) {
        if (typeof key !== 'string' || key.length === 0) {
            throw new Error('Invalid header: key must be a non-empty string')
        }
        if (key.length > MAX_KEY_LENGTH) {
            throw new Error(`Invalid header "${key}": key exceeds ${MAX_KEY_LENGTH} chars`)
        }
        if (!RFC7230_TOKEN.test(key)) {
            throw new Error(`Invalid header "${key}": key contains illegal characters`)
        }

        const lower = key.toLowerCase()
        if (DENIED_HEADER_NAMES.has(lower) || DENIED_HEADER_PREFIXES.some((p) => lower.startsWith(p))) {
            throw new Error(`Invalid header "${key}": this header name is not allowed`)
        }

        if (typeof value !== 'string') {
            throw new Error(`Invalid header "${key}": value must be a string`)
        }
        if (value.length > MAX_VALUE_LENGTH) {
            throw new Error(`Invalid header "${key}": value exceeds ${MAX_VALUE_LENGTH} chars`)
        }
        for (let i = 0; i < value.length; i++) {
            const code = value.charCodeAt(i)
            if (code === 0x0d || code === 0x0a || (code < 0x20 && code !== 0x09)) {
                throw new Error(`Invalid header "${key}": value contains illegal control characters`)
            }

View on GitHub (pinned to abe4a8601a)

Solutions

1. Use the bare header name without colon or value (e.g. 'Content-Type').
2. Trim whitespace from keys before submitting.
3. Restrict to RFC 7230 token characters: alphanumerics and !#$%&'*+-.^_`|~.

Example fix

// before
validateCustomHeaders({ 'Content-Type: application/json': '' }) // throws
validateCustomHeaders({ ' X-Custom ': 'v' }) // throws (spaces)

// after
validateCustomHeaders({ 'Content-Type': 'application/json' })
validateCustomHeaders({ 'X-Custom': 'v' })

// Reject non-token keys before validation
const RFC7230_TOKEN = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/
function onlyTokenKeys(headers) {
    return Object.fromEntries(Object.entries(headers).filter(([k]) => RFC7230_TOKEN.test(k)))
}

function keysAreRfc7230Tokens(headers) {
    const re = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/
    return Object.keys(headers).every((k) => re.test(k))
}

try {
    validateCustomHeaders(headers)
} catch (e) {
    if (/illegal characters/i.test(e.message)) {
        // strip colon/value and trim, then retry
        headers = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.trim().split(':')[0].trim(), v]))
    } else throw e
    validateCustomHeaders(headers)
}

When it happens

Trigger: Header name contains a colon (e.g. 'Content-Type: text/plain' used as the name), a space, a slash, an equals sign, a trailing/leading space or newline, or any non-ASCII (UTF-8) character.

Common situations: User pasted 'Key: Value' into the key field; copy included a trailing space or newline; experimental Unicode header name; name includes a parenthetical or other punctuation.

Related errors

• Invalid headers: expected an object
• Invalid headers: too many entries (max ${MAX_HEADERS})
• Invalid header: key must be a non-empty string
• Invalid header "${key}": key exceeds ${MAX_KEY_LENGTH} chars
• Invalid header "${key}": this header name is not allowed

AI-assisted analysis of FlowiseAI/Flowise@abe4a8601a (2026-08-12). Data as JSON: /api/errors/47d69d8e792d3701. Report an issue: GitHub.