What causes "failed to scan transactionGroups" in SigNoz/signoz?

Inspect the offending row's column and fix or NULL-out invalid JSON via SQL

errors.CodeInternal

errors.CodeInternal

Error message

failed to scan transactionGroups

What it means

TransactionGroups.Scan implements sql.Scanner for reading the column from the database. After converting the driver value to bytes it calls NewTransactionGroups to parse/validate the JSON; a parse or validation failure is wrapped as an internal error with 'failed to scan transactionGroups'.

Source

Thrown at pkg/types/authtypes/transaction.go:137

func (groups *TransactionGroups) Scan(value any) error {
	if value == nil {
		*groups = make(TransactionGroups, 0)
		return nil
	}

	var data []byte
	switch typed := value.(type) {
	case string:
		data = []byte(typed)
	case []byte:
		data = typed
	default:
		return errors.Newf(errors.TypeInternal, errors.CodeInternal, "unsupported type %T for transaction groups", value)
	}

	parsed, err := NewTransactionGroups(data)
	if err != nil {
		return errors.Wrap(err, errors.TypeInternal, errors.CodeInternal, "failed to scan transactionGroups")
	}

	*groups = parsed
	return nil
}

func (transaction *Transaction) UnmarshalJSON(data []byte) error {
	var shadow = struct {
		Relation Relation
		Object   coretypes.Object
	}{}

	err := json.Unmarshal(data, &shadow)
	if err != nil {
		return err
	}

	txn, err := NewTransaction(shadow.Relation, shadow.Object)

View on GitHub (pinned to 5069bf80b0)

Solutions

Inspect the offending row's column and fix or NULL-out invalid JSON via SQL
Check for format changes in NewTransactionGroups after upgrades and migrate stored data
If the column is legitimately empty, ensure it stores valid empty-group JSON or NULL handled by the driver

Example fix

// before (row contains)
{"groups": [ {"id": 1, }

// after
{"groups": [{"id": "...", "role_grants": []}]}

Defensive patterns

Strategy: try-catch

Try / catch

if err := rows.Scan(&groups, ...); err != nil {
    if strings.Contains(err.Error(), "failed to scan transactionGroups") {
        // quarantine row, alert ops, skip processing
        log.Error("corrupt transactionGroups column", "id", rowID)
        continue
    }
    return err
}

Prevention

Never hand-edit groups columns with raw SQL
Add migration checks after upgrades that alter TransactionGroups format

When it happens

Trigger: Reading a row whose transaction groups column contains malformed JSON or data that violates NewTransactionGroups validation (wrong shape, unknown fields with strict parsing, null where an object is required).

Common situations: Corrupted rows written by an older version or manual SQL updates; schema/format drift after an upgrade changes TransactionGroups validation rules; truncated column values.

Related errors

AI-assisted analysis of SigNoz/signoz@5069bf80b0 (2026-08-28). Data as JSON: /api/errors/c1f8557badca62ad. Report an issue: GitHub.