{"record":{"id":"e0d08f2b75a9dc04","repo":"goharbor/harbor","slug":"notfoundcode","errorCode":"NotFoundCode","errorMessage":"the reference tries to refer a non existing label %d or artifact %d","messagePattern":"the reference tries to refer a non existing label (.+?) or artifact (.+?)","errorType":"error_code","errorClass":"lib/errors.Error","httpStatus":404,"severity":"error","filePath":"src/pkg/label/dao/dao.go","lineNumber":169,"sourceCode":"\tlabels := []*model.Label{}\n\tif _, err = ormer.Raw(sql, artifactID).QueryRows(&labels); err != nil {\n\t\treturn nil, err\n\t}\n\treturn labels, nil\n}\nfunc (d *defaultDAO) CreateReference(ctx context.Context, ref *model.Reference) (int64, error) {\n\tormer, err := orm.FromContext(ctx)\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\tid, err := ormer.Insert(ref)\n\tif err != nil {\n\t\tif e := orm.AsConflictError(err, \"label %d is already added to the artifact %d\",\n\t\t\tref.LabelID, ref.ArtifactID); e != nil {\n\t\t\terr = e\n\t\t} else if e := orm.AsForeignKeyError(err, \"the reference tries to refer a non existing label %d or artifact %d\",\n\t\t\tref.LabelID, ref.ArtifactID); e != nil {\n\t\t\terr = errors.New(e).WithCode(errors.NotFoundCode).WithMessage(e.Message)\n\t\t}\n\t}\n\treturn id, err\n}\n\nfunc (d *defaultDAO) DeleteReference(ctx context.Context, id int64) error {\n\tormer, err := orm.FromContext(ctx)\n\tif err != nil {\n\t\treturn err\n\t}\n\tn, err := ormer.Delete(&model.Reference{\n\t\tID: id,\n\t})\n\tif err != nil {\n\t\treturn err\n\t}\n\tif n == 0 {\n\t\treturn errors.NotFoundError(nil).WithMessagef(\"label reference %d not found\", id)","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/goharbor/harbor/blob/7b2fd08cc568955cca339afeefab27372840d936/src/pkg/label/dao/dao.go#L151-L187","documentation":"Returned when inserting a row into the label-artifact reference table violates a foreign key constraint: the LabelID or ArtifactID in the new Reference does not exist in the database (label or artifact row missing/deleted). Harbor converts the ORM foreign-key error into a 404 NotFoundCode, surfaced by POST /api/v2.0/projects/{project}/repositories/{repo}/artifacts/{reference}/labels.","triggerScenarios":"POST .../artifacts/{reference}/labels with body {\"id\": <labelID>} where labelID does not exist (deleted or wrong environment's ID), points to a label in another project, or the artifact was concurrently deleted (e.g. garbage collect / retention job) between resolution and insert.","commonSituations":"Scripts or UI code caching label IDs that were re-created (IDs change across environments/DB rebuilds); attaching a project-scoped label from a different project; races between label deletion and an automated labeling pipeline; copied API examples with hardcoded label IDs.","solutions":["List the labels actually visible to the artifact's project (GET /api/v2.0/projects/{project_id}/labels and GET /api/v2.0/labels?scope=g) and re-submit with a current ID.","Verify the artifact exists (GET .../artifacts/{reference}) and re-resolve it if a retention/GC job may have deleted it.","If the label was deleted, re-create it and re-attach, or remove that step from your automation."],"exampleFix":"# before\ncurl -X POST https://harbor/api/v2.0/projects/myproj/repositories/myrepo/artifacts/sha256:abc.../labels -d '{\"id\": 42}'\n# after: re-list labels to get a valid id first\ncurl https://harbor/api/v2.0/projects/1/labels   # -> pick existing id, e.g. 7\ncurl -X POST https://harbor/api/v2.0/projects/myproj/repositories/myrepo/artifacts/sha256:abc.../labels -d '{\"id\": 7}'","handlingStrategy":"validation","validationCode":"# REST: resolve label and artifact immediately before attaching\n# label must appear in project labels or global labels\nlabels = GET /api/v2.0/projects/{project_id}/labels + GET /api/v2.0/labels?scope=g\nif label_id not in {l.id for l in labels}: fail(\"label id unknown\")\nart = GET /api/v2.0/projects/{project}/repositories/{repo}/artifacts/{reference}\nif art is 404: fail(\"artifact gone\")","typeGuard":null,"tryCatchPattern":"Catch HTTP 404 from POST .../artifacts/{reference}/labels; distinguish FK-not-found (re-list labels and retry once with a fresh ID) from artifact-not-found (skip — artifact deleted by retention/GC).","preventionTips":["Never cache label IDs across environments or long periods — look them up by name per run.","Use labels from the target project or global scope only.","In pipelines, tolerate and re-resolve on 404 since retention/GC can delete either side concurrently."],"tags":["labels","artifacts","database","foreign-key","api"],"backgroundTag":null,"analyzedSha":"7b2fd08cc568955cca339afeefab27372840d936","analyzedAt":"2026-08-16T00:00:10.961Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}