vitessio/vitess · error

unknown topo protobuf type for %v

Error message

unknown topo protobuf type for %v

What it means

DecodeContent maps a topo file path/name to a protobuf type for decoding stored topo data. When the path doesn't match any known topo directory pattern and JSON output was requested, it fails with 'unknown topo protobuf type'. Without json=true it degrades to returning the raw bytes.

Source

Thrown at go/vt/topo/decode.go:69

		p = new(vschemapb.SrvVSchema)
	case SrvKeyspaceFile:
		p = new(topodatapb.SrvKeyspace)
	case RoutingRulesFile:
		p = new(vschemapb.RoutingRules)
	case CommonRoutingRulesFile:
		switch path.Base(dir) {
		case "keyspace":
			p = new(vschemapb.KeyspaceRoutingRules)
		}
	default:
		switch dir {
		case "/" + GetExternalVitessClusterDir():
			p = new(topodatapb.ExternalVitessCluster)
		default:
		}
		if p == nil {
			if json {
				return "", fmt.Errorf("unknown topo protobuf type for %v", name)
			}
			return string(data), nil
		}
	}

	if err := proto.Unmarshal(data, p); err != nil {
		return string(data), err
	}

	var marshalled []byte
	var err error
	if json {
		// Maintain snake_case for the JSON output as this keeps the output consistent across
		// vtctldclient commands and it is needed if the returned value is used as input to
		// vtctldclient, e.g. for ApplyRoutingRules.
		pm := protojson.MarshalOptions{
			Indent:        "  ",
			UseProtoNames: true,

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Call without json=true to get the raw content instead of the protobuf decode.
2. Check the path is a standard topo directory; move custom data out of the topo storage.
3. Upgrade the client binary so it knows the new topo protobuf type (e.g. newer GetExternalVitessClusterDir entries).

Example fix

// before
str, err := ts.DecodeContent(ctx, topo.CellInfoFileName(cell), data, true) // unknown type
// after
str, err := ts.DecodeContent(ctx, topo.CellInfoFileName(cell), data, false) // returns raw string

switch {
case strings.HasPrefix(name, "/keyspaces"), strings.HasPrefix(name, "/cells"), strings.HasPrefix(name, "/tablets"):
    // known topo types, safe to decode with json=true
}
// otherwise use json=false

out, err := ts.DecodeContent(ctx, name, data, true)
if err != nil && strings.Contains(err.Error(), "unknown topo protobuf type") {
    out, err = ts.DecodeContent(ctx, name, data, false) // raw fallback
}

When it happens

Trigger: Calling DecodeContent with json=true on a file under an unrecognized topo directory (not tablets, keyspaces, shards, replication, vschemas, cells aliases, external clusters, etc.), e.g. a plugin-added or custom topo entry.

Common situations: vtctl topo commands (cat, get) hitting a custom cell or a new topo directory introduced by a newer Vitess than the tool binary; manual files placed in the topo storage.

Related errors

• cells alias %v is not valid: %v
• cell set overlaps with existing alias %v
• GetKeyspaces: %w
• GetKeyspace(%v): %w
• fromTS.GetKeyspaces: %w

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/c9f0e3a81dd6a46e. Report an issue: GitHub.