failed to decode protobuf JSON; verify field names, value ty

Error message

failed to decode protobuf JSON; verify field names, value types, and JSON syntax

What it means

readDeploymentProtoJSON unmarshals the file with protojson using DiscardUnknown: false, so any JSON malformation, wrong field name casing, or wrong value type fails. When the underlying error is not a recognizable unknown-field error, it is replaced with the generic hint "failed to decode protobuf JSON; verify field names, value types, and JSON syntax", losing the original detail.

Source

Thrown at store/deployment_config.go:153

	info, err = file.Stat()
	if err != nil {
		return errors.Wrap(err, "failed to inspect file")
	}
	if !info.Mode().IsRegular() {
		return errors.New("file must resolve to a regular file")
	}
	content, err := io.ReadAll(io.LimitReader(file, maxDeploymentConfigurationSize+1))
	if err != nil {
		return errors.Wrap(err, "failed to read file")
	}
	if len(content) > maxDeploymentConfigurationSize {
		return errors.Errorf("file exceeds %d bytes", maxDeploymentConfigurationSize)
	}
	if err := (protojson.UnmarshalOptions{DiscardUnknown: false}).Unmarshal(content, message); err != nil {
		if matches := protoJSONUnknownFieldMatcher.FindStringSubmatch(err.Error()); len(matches) == 2 {
			return errors.Errorf("failed to decode protobuf JSON: unknown field %q", matches[1])
		}
		return errors.New("failed to decode protobuf JSON; verify field names, value types, and JSON syntax")
	}
	return nil
}

func validateDeploymentIdentityProvider(provider *storepb.IdentityProvider) error {
	if provider.Id != 0 {
		return errors.New("id must be omitted")
	}
	if !base.UIDMatcher.MatchString(provider.Uid) {
		return errors.New("uid is invalid")
	}
	if strings.TrimSpace(provider.Name) == "" {
		return errors.New("name is required")
	}
	if provider.Type != storepb.IdentityProvider_OAUTH2 {
		return errors.New("type must be OAUTH2")
	}
	if provider.IdentifierFilter != "" {

View on GitHub (pinned to 14d757ce1f)

Solutions

Validate the file with a JSON linter first (jsonschema/json tooling) to catch syntax errors
Match field names and value types exactly to the proto message (see proto/store definitions), including enum name spellings
Re-save without BOM; keep the file under maxDeploymentConfigurationSize
Reproduce with protojson.Unmarshal locally to get the underlying error message

Example fix

// before (memos-idp-x.json)
{ "name": "OAuth", "type": 1, "config": { "oauth2": { "clientId": "abc", "authUrl": "https://sso/auth" } } }
// after — use enum names and check exact field names against the proto
{ "uid": "github-oauth", "name": "OAuth", "type": "OAUTH2", "config": { "oauth2": { "clientId": "abc", "authUrl": "https://sso/auth" } } }

Defensive patterns

Strategy: validation

Validate before calling

data, _ := os.ReadFile(path)
if !json.Valid(data) {
    return fmt.Errorf("deployment config is not valid JSON")
}
if err := protojson.UnmarshalOptions{DiscardUnknown: false}.Unmarshal(data, msg); err != nil {
    return fmt.Errorf("proto decode failed: %w", err) // keep the detailed error
}

Prevention

Validate deployment JSON with json.Valid and a linter before startup
Cross-check field names, enum spellings, and types against the proto definitions
Save config files without a UTF-8 BOM

When it happens

Trigger: A deployment JSON file with wrong proto field casing (camelCase vs snake_case mix-ups are tolerated by protojson, but typos are not), string where a number is expected, enum values not matching proto enum names, trailing commas, or a BOM.

Common situations: Hand-edited IdP bootstrap JSON; files written with UTF-8 BOM by Windows editors; field names taken from a different proto version; booleans passed as "true" strings.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of usememos/memos@14d757ce1f (2026-08-15). Data as JSON: /api/errors/86a3ce0d9fc2d6e1. Report an issue: GitHub.