temporalio/temporal · error

queue with type %v and name %v has invalid encoding: %w

Error message

queue with type %v and name %v has invalid encoding: %w

What it means

extractQueueMetadata verifies that a queue V2 metadata row was encoded with proto3; any other MetadataEncoding string triggers serialization.NewUnknownEncodingTypeError wrapped with the queue type/name. It guards against reading metadata written by an incompatible encoder or corrupted rows.

Source

Thrown at common/persistence/sql/queue_v2.go:352

	case sqlplugin.Tx:
		metadata, err = tc.SelectFromQueueV2MetadataForUpdate(ctx, filter)
	default:
		metadata, err = tc.SelectFromQueueV2Metadata(ctx, filter)
	}
	if err != nil {
		if errors.Is(err, sql.ErrNoRows) {
			return nil, persistence.NewQueueNotFoundError(queueType, queueName)
		}
		return nil, serviceerror.NewUnavailablef(
			"failed to get metadata for queue with type: %v and name: %v. Error: %v", queueType, queueName, err,
		)
	}
	return q.extractQueueMetadata(metadata)
}

func (q queueV2) extractQueueMetadata(metadataRow *sqlplugin.QueueV2MetadataRow) (*persistencespb.Queue, error) {
	if metadataRow.MetadataEncoding != enumspb.ENCODING_TYPE_PROTO3.String() {
		return nil, fmt.Errorf(
			"queue with type %v and name %v has invalid encoding: %w",
			metadataRow.QueueType,
			metadataRow.QueueName,
			serialization.NewUnknownEncodingTypeError(metadataRow.MetadataEncoding, enumspb.ENCODING_TYPE_PROTO3),
		)
	}
	qm := &persistencespb.Queue{}
	err := qm.Unmarshal(metadataRow.MetadataPayload)
	if err != nil {
		return nil, serialization.NewDeserializationError(
			enumspb.ENCODING_TYPE_PROTO3,
			fmt.Errorf("unmarshal payload for queue with type %v and name %v failed: %w",
				metadataRow.QueueType,
				metadataRow.QueueName,
				err),
		)
	}
	return qm, nil

View on GitHub (pinned to bde624efd1)

Solutions

1. Identify the queue from the message (type and name are printed) and inspect its metadata row's MetadataEncoding value in the database.
2. Rewrite the metadata row with valid proto3-encoded payload (MetadataEncoding = "proto3") if it was hand-modified.
3. Ensure all cluster nodes run a compatible Temporal version so no legacy encodings are written.
4. Delete and recreate the queue if its metadata is unrecoverable.

// inspect the offending row before use
var enc string
db.QueryRow("SELECT metadata_encoding FROM queue_metadata_v2 WHERE queue_type=? AND queue_name=?", qt, qn).Scan(&enc)
if enc != "proto3" {
    // row is unreadable by this code path; repair or recreate
}

qm, err := store.GetQueueMetadata(ctx, req)
if err != nil && strings.Contains(err.Error(), "invalid encoding") {
    // rebuild/recreate the queue; metadata is incompatible
}

When it happens

Trigger: getQueueMetadata or getMessageCountAndLastID reads a queue_metadata_v2 row whose MetadataEncoding column is not "proto3", then calls extractQueueMetadata.

Common situations: Rows written by a custom tool or older/experimental version using a different encoding; manual DB edits; corruption of the MetadataEncoding column; mixed-version cluster during upgrade.

Related errors

• unmarshal payload for queue with type %v and name %v failed:
• serializer error
• corrupted history event batch, eventID is not contiguous
• history task from queue has nil blob
• cannot serialize HSM task. unable to cast to expected type

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/f2ba9160620c0a65. Report an issue: GitHub.