grpc/grpc-go · error

%s: %v

Error message

%s: %v

What it means

During channel construction (clientconn.go:229-233), if a default service config was supplied via WithDefaultServiceConfig and parsing it fails, the parser error is wrapped with the prefix "grpc: the provided default service config is invalid". The channel aborts creation entirely.

Source

Thrown at clientconn.go:232

	if err := cc.initParsedTargetAndResolverBuilder(); err != nil {
		return nil, err
	}

	for _, opt := range globalPerTargetDialOptions {
		opt.DialOptionForTarget(cc.parsedTarget.URL).apply(&cc.dopts)
	}

	chainUnaryClientInterceptors(cc)
	chainStreamClientInterceptors(cc)

	if err := cc.validateTransportCredentials(); err != nil {
		return nil, err
	}

	if cc.dopts.defaultServiceConfigRawJSON != nil {
		scpr := parseServiceConfig(*cc.dopts.defaultServiceConfigRawJSON, cc.dopts.maxCallAttempts)
		if scpr.Err != nil {
			return nil, fmt.Errorf("%s: %v", invalidDefaultServiceConfigErrPrefix, scpr.Err)
		}
		cc.dopts.defaultServiceConfig, _ = scpr.Config.(*ServiceConfig)
	}
	cc.keepaliveParams = cc.dopts.copts.KeepaliveParams

	if err = cc.initAuthority(); err != nil {
		return nil, err
	}

	// Register ClientConn with channelz. Note that this is only done after
	// channel creation cannot fail.
	cc.channelzRegistration(target)
	channelz.Infof(logger, cc.channelz, "parsed dial target is: %#v", cc.parsedTarget)
	channelz.Infof(logger, cc.channelz, "Channel authority set to %q", cc.authority)

	cc.csMgr = newConnectivityStateManager(cc.ctx, cc.channelz)
	cc.pickerWrapper = newPickerWrapper()

View on GitHub (pinned to 03255a9237)

Solutions

1. Validate the JSON string with a JSON parser and the gRPC service config schema before passing it to WithDefaultServiceConfig.
2. Read the wrapped error tail — it names the exact offending field (e.g. "error: methodConfig[{...}]") — and fix that field.
3. If migrating versions, regenerate the default config or drop unsupported keys.

Example fix

// before
grpc.WithDefaultServiceConfig(`{"methodConfig":[{"methodName":[]}]}`)
// after
grpc.WithDefaultServiceConfig(`{"methodConfig":[{"name":[{"service":"pkg.Svc","method":"Do"}],"retryPolicy":{"maxAttempts":3}}]}`)

// Parse the default service config with the same parser before dialing.
func validateDefaultCfg(js string) error {
    jsPtr := js
    scpr := parseServiceConfig(&jsPtr, 1) // or grpc.ParseServiceConfig(js) via public API
    return scpr.Err
}

When it happens

Trigger: Passing malformed JSON to grpc.WithDefaultServiceConfig("..."), or a structurally-valid but semantically invalid config (bad methodConfig, retry policy, or LB policy). NewClient / Dial returns this error before any connection attempt.

Common situations: Hand-edited default service config JSON with a syntax error; a config generated for a newer gRPC version with unsupported fields; invalid retry parameters or loadBalancingConfig.

Related errors

• wrr: errorUtilizationPenalty must be non-negative
• ClientConn's authority from transport creds %q and dial opti
• gcpauthn: cache_config.cache_size must be greater than zero
• rbac: principal header matcher for %v is :scheme or starts w
• no error details for status with code OK

AI-assisted analysis of grpc/grpc-go@03255a9237 (2026-08-07). Data as JSON: /api/errors/ab4774695273a07d. Report an issue: GitHub.