{"record":{"id":"81c5c677cb50ddba","repo":"temporalio/temporal","slug":"errqueuealreadyexists","errorCode":"ErrQueueAlreadyExists","errorMessage":"%w: queue type %v and name %v","messagePattern":"%w: queue type (.+?) and name (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"common/persistence/sql/queue_v2.go","lineNumber":204,"sourceCode":"\trequest *persistence.InternalCreateQueueRequest,\n) (*persistence.InternalCreateQueueResponse, error) {\n\tpayload := persistencespb.Queue{\n\t\tPartitions: map[int32]*persistencespb.QueuePartition{\n\t\t\tdefaultPartition: {\n\t\t\t\tMinMessageId: persistence.FirstQueueMessageID,\n\t\t\t},\n\t\t},\n\t}\n\tbytes, _ := payload.Marshal()\n\trow := sqlplugin.QueueV2MetadataRow{\n\t\tQueueType:        request.QueueType,\n\t\tQueueName:        request.QueueName,\n\t\tMetadataPayload:  bytes,\n\t\tMetadataEncoding: enumspb.ENCODING_TYPE_PROTO3.String(),\n\t}\n\t_, err := q.DB.InsertIntoQueueV2Metadata(ctx, &row)\n\tif q.DB.IsDupEntryError(err) {\n\t\treturn nil, fmt.Errorf(\n\t\t\t\"%w: queue type %v and name %v\",\n\t\t\tpersistence.ErrQueueAlreadyExists,\n\t\t\trequest.QueueType,\n\t\t\trequest.QueueName,\n\t\t)\n\t}\n\tif err != nil {\n\t\treturn nil, serviceerror.NewUnavailablef(\n\t\t\t\"CreateQueue failed for queue with type: %v and name: %v. InsertIntoQueueV2Metadata operation failed. Error: %v\",\n\t\t\trequest.QueueType,\n\t\t\trequest.QueueName,\n\t\t\terr,\n\t\t)\n\t}\n\treturn &persistence.InternalCreateQueueResponse{}, nil\n}\n\nfunc (q *queueV2) RangeDeleteMessages(","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/persistence/sql/queue_v2.go#L186-L222","documentation":"CreateQueue in the queue V2 store detects a duplicate-entry error from the database when inserting queue V2 metadata, and wraps it with persistence.ErrQueueAlreadyExists. This is an expected, typed conflict: the caller is trying to create a queue whose (queue type, queue name) pair already exists in the cluster.","triggerScenarios":"Calling CreateQueue with a QueueType/QueueName combination that already has a metadata row; the DB insert returns a duplicate-key error matched by q.DB.IsDupEntryError.","commonSituations":"Re-running an idempotent-but-non-idempotent queue creation path; two services racing to create the same named queue; retrying CreateQueue after a timeout where the first attempt actually committed.","solutions":["Treat as expected: check errors.Is(err, persistence.ErrQueueAlreadyExists) and proceed as if the queue exists (idempotent create).","Use a different queue name if a new distinct queue was intended.","Delete the existing queue first if recreation is intended (e.g., DeleteQueue), then create again."],"exampleFix":"// before\n_, err := store.CreateQueue(ctx, req)\nif err != nil { return err }\n// after\n_, err := store.CreateQueue(ctx, req)\nif errors.Is(err, persistence.ErrQueueAlreadyExists) {\n    return nil // already created; idempotent\n}\nif err != nil { return err }","handlingStrategy":"type-guard","validationCode":"// pre-check if queue already exists via GetQueueMetadata\n_, err := store.GetQueueMetadata(ctx, &persistence.InternalGetQueueMetadataRequest{\n    QueueType: req.QueueType, QueueName: req.QueueName,\n})\nexists := err == nil","typeGuard":"func isQueueAlreadyExists(err error) bool {\n    return errors.Is(err, persistence.ErrQueueAlreadyExists)\n}","tryCatchPattern":"_, err := store.CreateQueue(ctx, req)\nif isQueueAlreadyExists(err) {\n    return nil // treat as success for idempotent creation\n}\nreturn err","preventionTips":["Make queue creation idempotent by handling ErrQueueAlreadyExists as success.","Use deterministic queue names so repeated deploys don't collide.","Serialize queue-creation calls for the same name through a single owner."],"tags":["database","queue","duplicate-key","conflict"],"backgroundTag":"resource-already-exists","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}