websockets/ws · error · Error

Unknown parameter "${key}"

Error message

Unknown parameter "${key}"

What it means

Thrown by normalizeParams() (permessage-deflate.js:286-287) when a parameter key is not one of the four recognized permessage-deflate parameters: client_max_window_bits, server_max_window_bits, client_no_context_takeover, or server_no_context_takeover. Any other key in the configuration is rejected as unknown, preventing unrecognized or typo'd parameters from being silently accepted.

Source

Thrown at lib/permessage-deflate.js:287

        } else if (key === 'server_max_window_bits') {
          const num = +value;
          if (!Number.isInteger(num) || num < 8 || num > 15) {
            throw new TypeError(
              `Invalid value for parameter "${key}": ${value}`
            );
          }
          value = num;
        } else if (
          key === 'client_no_context_takeover' ||
          key === 'server_no_context_takeover'
        ) {
          if (value !== true) {
            throw new TypeError(
              `Invalid value for parameter "${key}": ${value}`
            );
          }
        } else {
          throw new Error(`Unknown parameter "${key}"`);
        }

        params[key] = value;
      });
    });

    return configurations;
  }

  /**
   * Decompress data. Concurrency limited.
   *
   * @param {Buffer} data Compressed data
   * @param {Boolean} fin Specifies whether or not this is the last fragment
   * @param {Function} callback Callback
   * @public
   */
  decompress(data, fin, callback) {

View on GitHub (pinned to ae1de54330)

Solutions

1. Check the parameter name in the error message: if it is a typo of a known parameter, correct the spelling.
2. Remove any non-standard parameters that are not part of the permessage-deflate specification (client_max_window_bits, server_max_window_bits, client_no_context_takeover, server_no_context_takeover).
3. Fix the peer or middleware that introduces the unknown parameter.
4. If a custom extension with extra parameters is needed, use a separate extension implementation rather than permessage-deflate.

Example fix

// before — misspelled parameter name
const header = 'permessage-deflate; sever_max_window_bits=10';

// after
const header = 'permessage-deflate; server_max_window_bits=10';

const KNOWN_PARAMS = new Set([
  'client_max_window_bits',
  'server_max_window_bits',
  'client_no_context_takeover',
  'server_no_context_takeover'
]);

function hasOnlyKnownParams(config) {
  return Object.keys(config).every((key) => KNOWN_PARAMS.has(key));
}

function isKnownPerMessageDeflateParam(key) {
  return [
    'client_max_window_bits',
    'server_max_window_bits',
    'client_no_context_takeover',
    'server_no_context_takeover'
  ].includes(key);
}

try {
  perMessageDeflate.normalizeParams(configurations);
} catch (err) {
  if (err.message.startsWith('Unknown parameter')) {
    console.warn('Unrecognized permessage-deflate parameter:', err.message);
  } else {
    throw err;
  }
}

When it happens

Trigger: normalizeParams() is called with a configuration containing a parameter name outside the four allowed, e.g. from a header like 'permessage-deflate; max_window_bits=10', '...; context_takeover', '...; compress=true', or '...; custom_param=x'. A typo such as 'sever_max_window_bits' would also hit this.

Common situations: A peer advertises a non-standard or misspelled parameter. A developer adds a custom parameter name that is not part of RFC 7692. A proxy injects an unknown parameter. A typo in a hand-crafted header.

Related errors

• Invalid value for parameter "${key}": ${value}
• None of the extension offers can be accepted
• Unexpected parameter "client_no_context_takeover"
• Unexpected or invalid parameter "client_max_window_bits"
• Parameter "${key}" must have only a single value

AI-assisted analysis of websockets/ws@ae1de54330 (2026-08-03). Data as JSON: /data/errors/8a449514d3c08f6b.json. Report an issue: GitHub.