{"record":{"id":"2f87a9d4d157e164","repo":"Tencent/WeKnora","slug":"failed-to-allocate-unique-resource-handle","errorCode":null,"errorMessage":"failed to allocate unique resource handle","messagePattern":"failed to allocate unique resource handle","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/application/service/resource.go","lineNumber":109,"sourceCode":"\t\t\tLocationHash:     locationHash,\n\t\t\tKind:             meta.Kind,\n\t\t\tMimeType:         meta.MimeType,\n\t\t\tOriginalName:     meta.OriginalName,\n\t\t\tSize:             meta.Size,\n\t\t\tContentHash:      meta.ContentHash,\n\t\t\tLifecycle:        lifecycle,\n\t\t}\n\t\tif err := s.repo.Create(ctx, resource); err == nil {\n\t\t\treturn types.BuildResourcePath(handle), nil\n\t\t} else if !strings.Contains(strings.ToLower(err.Error()), \"unique\") {\n\t\t\treturn \"\", err\n\t\t}\n\t\texisting, lookupErr := s.repo.GetByTenantLocation(ctx, tenantID, locationHash)\n\t\tif lookupErr == nil && existing != nil {\n\t\t\treturn types.BuildResourcePath(existing.Handle), nil\n\t\t}\n\t}\n\treturn \"\", fmt.Errorf(\"failed to allocate unique resource handle\")\n}\n\nfunc (s *resourceCatalog) Resolve(ctx context.Context, reference string) (*types.StoredResource, error) {\n\thandle, ok := types.ParseResourcePath(reference)\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"invalid resource reference\")\n\t}\n\tresource, err := s.repo.GetByHandle(ctx, handle)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif resource == nil {\n\t\treturn nil, fmt.Errorf(\"resource not found\")\n\t}\n\treturn resource, nil\n}\n\nfunc (s *resourceCatalog) ResolvePath(ctx context.Context, value string) (string, *types.StoredResource, error) {","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/application/service/resource.go#L91-L127","documentation":"Register exhausts its retry loop trying to mint a resource handle that does not already exist for the tenant/location hash. If the repo keeps returning an existing row (or keeps failing uniqueness checks) for every attempt, it gives up with this error. It signals handle-space contention or a deterministic handle generator colliding with stored rows, not a caller input problem.","triggerScenarios":"Calling Register when the tenant+locationHash row already exists but the lookup guard above (GetByTenantLocation) misses it (e.g. eventual-consistent replica, mismatched hash input), or the handle generation loop repeatedly produces handles already claimed in the repo.","commonSituations":"Re-registering the same physical resource after a partial migration; concurrent Register calls racing on near-identical locations; a changed locationHash algorithm so lookups miss old rows while new handles keep colliding.","solutions":["Pre-check with repo.GetByTenantLocation using the exact same tenantID/locationHash inputs before calling Register to see if the row already exists","Verify the locationHash computation matches what was used when the row was created (version skew)","Retry after a short delay if concurrent Register calls are racing; serialize registration per tenant","Inspect the repo for stuck/duplicate rows that the unique constraint keeps colliding with"],"exampleFix":"// before\nexisting, lookupErr := s.repo.GetByTenantLocation(ctx, tenantID, locationHash)\nif lookupErr == nil && existing != nil {\n    return types.BuildResourcePath(existing.Handle), nil\n}\n// after\nexisting, lookupErr := s.repo.GetByTenantLocation(ctx, tenantID, locationHash)\nif lookupErr != nil {\n    return \"\", fmt.Errorf(\"lookup resource location: %w\", lookupErr)\n}\nif existing != nil {\n    return types.BuildResourcePath(existing.Handle), nil\n}","handlingStrategy":"retry","validationCode":"existing, err := repo.GetByTenantLocation(ctx, tenantID, locationHash)\nif err == nil && existing != nil { return types.BuildResourcePath(existing.Handle), nil }","typeGuard":"func resourceHandleAllocated(handle string, r *types.StoredResource) bool { return r != nil && r.Handle == handle }","tryCatchPattern":"path, err := catalog.Register(ctx, tenantID, location)\nif err != nil && strings.Contains(err.Error(), \"failed to allocate unique resource handle\") {\n    time.Sleep(50 * time.Millisecond)\n    path, err = catalog.Register(ctx, tenantID, location) // bounded retry\n}","preventionTips":["Always reuse the returned path from a successful Register instead of re-registering","Serialize registration per tenant+location with a lock or unique index","Keep locationHash computation stable across deploys","Monitor collision rate in repo CreateGrant/CreateHandle failures"],"tags":["resource-catalog","uniqueness","collision"],"backgroundTag":"unique-resource-allocation-failed","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}