bytebase/bytebase · error

cannot convert collection name to string

Error message

cannot convert collection name to string

What it means

During MongoDB schema sync, the driver reads collection info entries returned by the server (from listCollections-style results). Each entry is an untyped map (bson.M), so it asserts that the entry has a "name" field and that the value is a string. This error is thrown when the "name" key exists but its value cannot be type-asserted to string, meaning the server returned an unexpected shape for the collection name.

Source

Thrown at backend/plugin/db/mongodb/sync.go:116

		if err := collectionList.Decode(&collection); err != nil {
			return nil, errors.Wrap(err, "failed to decode collection")
		}
		var tp string
		if t, ok := collection["type"]; ok {
			if s, ok := t.(string); ok && s == "collection" {
				tp = "collection"
			}
			if s, ok := t.(string); ok && s == "view" {
				tp = "view"
			}
		}
		name, ok := collection["name"]
		if !ok {
			return nil, errors.New("cannot get collection name from collection info")
		}
		collectionName, ok := name.(string)
		if !ok {
			return nil, errors.New("cannot convert collection name to string")
		}
		switch tp {
		case "collection":
			collectionNames = append(collectionNames, collectionName)
		case "view":
			viewNames = append(viewNames, collectionName)
		default:
			// Other types like system collections
		}
	}
	if err := collectionList.Err(); err != nil {
		return nil, errors.Wrap(err, "failed to list collection names")
	}
	if err := collectionList.Close(ctx); err != nil {
		return nil, errors.Wrap(err, "failed to close collection list")
	}
	slices.Sort(collectionNames)
	slices.Sort(viewNames)

View on GitHub (pinned to 1870550677)

Solutions

  1. Inspect the actual collection info returned by running db.runCommand({listCollections:1}) against the same database and check the name field's BSON type
  2. Upgrade the mongo driver and MongoDB server to compatible versions, since this normally never happens with genuine servers
  3. If connecting to a compatible service (DocumentDB, FerretDB), verify it implements listCollections with string name fields; file an issue with the raw collection info payload otherwise

Example fix

// before
collectionName, ok := name.(string)
if !ok {
	return nil, errors.New("cannot convert collection name to string")
}
// after
collectionName, ok := name.(string)
if !ok {
	return nil, errors.Wrapf(errors.New("cannot convert collection name to string"), "unexpected type %T for collection name", name)
}
Defensive patterns

Strategy: type-guard

Validate before calling

// before calling SyncDBSchema there is no direct pre-check; guard at the data boundary
for _, col := range collectionInfos {
	if nameVal, present := col["name"]; !present {
		return fmt.Errorf("collection info missing name")
	} else if _, isStr := nameVal.(string); !isStr {
		return fmt.Errorf("collection name has unexpected type %T", nameVal)
	}
}

Type guard

func asString(v any) (string, bool) {
	s, ok := v.(string)
	return s, ok
}

Try / catch

if err := driver.SyncDBSchema(ctx); err != nil {
	var se *errors.Error
	if stderrors.As(err, &se) && strings.Contains(se.Error(), "cannot convert collection name to string") {
		// log server response anomaly and skip this database
		return nil
	}
	return err
}

Prevention

When it happens

Trigger: SyncDBSchema iterates collection info maps where collection["name"] holds a non-string BSON value (e.g. null, a document, or a custom BSON type) instead of the expected string collection name.

Common situations: Corrupted or unusual metadata returned by the MongoDB server; a proxy or shim (e.g. DocumentDB emulation layers, mock servers in tests) that returns collection info in a different shape; BSON decoding quirks where the name field decodes to a non-string type.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of bytebase/bytebase@1870550677 (2026-09-06). Data as JSON: /api/errors/3081e1fc568700ee. Report an issue: GitHub.