grafana/k6 · error

unknown connect param: %q

Error message

unknown connect param: %q

What it means

Thrown by k6's gRPC Client.connect() when the params object contains a key that is not one of the recognized connect options. The parser in newConnectParams (internal/js/modules/k6/grpc/params.go:155-214) iterates every key of the object passed to connect() and only accepts: plaintext, timeout, reflect, reflectMetadata, maxReceiveSize, maxSendSize, tls, authority. Any other key hits the default branch and fails the whole connect call, so the error is a strict schema check, not a runtime/network problem.

Source

Thrown at internal/js/modules/k6/grpc/params.go:213

			result.MaxSendSize, ok = v.(int64)
			if !ok {
				return result, fmt.Errorf("invalid maxSendSize value: '%#v', it needs to be an integer", v)
			}
			if result.MaxSendSize < 0 {
				return result, fmt.Errorf("invalid maxSendSize value: '%#v, it needs to be a positive integer", v)
			}
		case "tls":
			if err := parseConnectTLSParam(result, v); err != nil {
				return result, err
			}
		case "authority":
			var ok bool
			result.Authority, ok = v.(string)
			if !ok {
				return result, fmt.Errorf("invalid authority value: '%#v', it needs to be a string", v)
			}
		default:
			return result, fmt.Errorf("unknown connect param: %q", k)
		}
	}

	return result, nil
}

func parseConnectTLSParam(params *connectParams, v any) error {
	var ok bool
	params.TLS, ok = v.(map[string]any)

	if !ok {
		return fmt.Errorf("invalid tls value: '%#v', expected (optional) keys: cert, key, password, and cacerts", v)
	}
	// optional map keys below
	if cert, certok := params.TLS["cert"]; certok {
		if _, ok = cert.(string); !ok {
			return fmt.Errorf("invalid tls cert value: '%#v', it needs to be a PEM formatted string", v)
		}

View on GitHub (pinned to 93accf6570)

Solutions

  1. Check the exact key name reported between the quotes in the message against the allowed list: plaintext, timeout, reflect, reflectMetadata, maxReceiveSize, maxSendSize, tls, authority.
  2. Remove the offending key from the object passed to client.connect(); if it is a call-level option (metadata, tags, timeout, discardResponseMessage), move it to the second argument of client.invoke() or client.newStream().
  3. Fix casing/typos, e.g. 'TLS' -> 'tls', 'reflectmetadata' -> 'reflectMetadata'.
  4. If you expected the option to exist, verify your k6 version's gRPC module documentation — the supported set is fixed by newConnectParams.

Example fix

// before
client.connect('grpc.example.com:443', {
  timeout: '5s',
  TLS: { cacerts: [ca] }, // unknown connect param: "TLS"
});

// after
client.connect('grpc.example.com:443', {
  timeout: '5s',
  tls: { cacerts: [ca] },
});
Defensive patterns

Strategy: validation

Validate before calling

const CONNECT_KEYS = new Set(['plaintext', 'timeout', 'reflect', 'reflectMetadata', 'maxReceiveSize', 'maxSendSize', 'tls', 'authority']);
function validateConnectParams(params = {}) {
  const unknown = Object.keys(params).filter((k) => !CONNECT_KEYS.has(k));
  if (unknown.length) {
    throw new Error(`unsupported connect option(s): ${unknown.join(', ')}; allowed: ${[...CONNECT_KEYS].join(', ')}`);
  }
}

Type guard

function isConnectParams(p) {
  return p == null || (typeof p === 'object' && Object.keys(p).every((k) => ['plaintext', 'timeout', 'reflect', 'reflectMetadata', 'maxReceiveSize', 'maxSendSize', 'tls', 'authority'].includes(k)));
}

Try / catch

try { client.connect(addr, params); } catch (e) { if (/unknown connect param/.test(e.message)) { /* strip bad keys and retry or fail fast with context */ } throw e; }

Prevention

When it happens

Trigger: Calling client.connect('host:port', { ... }) with a misspelled or unsupported option, e.g. { TLS: {...} } (uppercase), { timeouts: '5s' }, { userAgent: 'x' }, or copy-pasting an option that belongs to call params (metadata, tags, discardResponseMessage) into the connect options object.

Common situations: Porting a script from k6/http where option names differ; using a TLS key spelled 'TLS' instead of 'tls'; copying connect options from an older k6 example or another tool; adding call-level params (like 'metadata') to connect() instead of to client.invoke()/client.newStream().

Related errors

AI-assisted analysis of grafana/k6@93accf6570 (2026-08-15). Data as JSON: /api/errors/c8dff9e6d58919d0. Report an issue: GitHub.