{"record":{"id":"77794ceda69d87b6","repo":"AlistGo/alist","slug":"ref-w","errorCode":null,"errorMessage":"ref: %w","messagePattern":"ref: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/op/storage.go","lineNumber":140,"sourceCode":"\t\t\tstoragesMap.Store(driverStorage.MountPath, storageDriver)\n\t\t}\n\t}()\n\t// Unmarshal Addition\n\terr = utils.Json.UnmarshalFromString(driverStorage.Addition, storageDriver.GetAddition())\n\tif err == nil {\n\t\tif ref, ok := storageDriver.(driver.Reference); ok {\n\t\t\tif strings.HasPrefix(driverStorage.Remark, \"ref:/\") {\n\t\t\t\trefMountPath := driverStorage.Remark\n\t\t\t\ti := strings.Index(refMountPath, \"\\n\")\n\t\t\t\tif i > 0 {\n\t\t\t\t\trefMountPath = refMountPath[4:i]\n\t\t\t\t} else {\n\t\t\t\t\trefMountPath = refMountPath[4:]\n\t\t\t\t}\n\t\t\t\tvar refStorage driver.Driver\n\t\t\t\trefStorage, err = GetStorageByMountPath(refMountPath)\n\t\t\t\tif err != nil {\n\t\t\t\t\terr = fmt.Errorf(\"ref: %w\", err)\n\t\t\t\t} else {\n\t\t\t\t\terr = ref.InitReference(refStorage)\n\t\t\t\t\tif err != nil && errs.IsNotSupportError(err) {\n\t\t\t\t\t\terr = fmt.Errorf(\"ref: storage is not %s\", storageDriver.Config().Name)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\tif err == nil {\n\t\terr = storageDriver.Init(ctx)\n\t}\n\tstoragesMap.Store(driverStorage.MountPath, storageDriver)\n\tif err != nil {\n\t\tdriverStorage.SetStatus(err.Error())\n\t\terr = errors.Wrap(err, \"failed init storage\")\n\t} else {\n\t\tdriverStorage.SetStatus(WORK)","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/AlistGo/alist/blob/843d9dc8149126976b2625911e45a4d3ffd6f2f5/internal/op/storage.go#L122-L158","documentation":"During storage initialization, this storage is a 'reference' storage (its Remark starts with \"ref:/\" pointing at another storage's mount path). The referenced mount path cannot be resolved by GetStorageByMountPath, and the underlying error is wrapped as \"ref: %w\". It ultimately surfaces as \"failed init storage\".","triggerScenarios":"Adding a storage whose remark/driver config embeds ref:/<mount-path> where <mount-path> does not match any mounted storage (wrong path, trailing slash mismatch, or the target storage failed to load first).","commonSituations":"Renaming or deleting the referenced storage but leaving the reference storage in place; typos in the ref mount path; the referenced storage driver failing earlier in the init loop so it is absent from storagesMap.","solutions":["Verify the exact mount path in the ref: remark matches an existing storage's mount path (copy-paste it from the storages list)","Ensure the referenced storage itself initializes successfully — check its status first","Re-create the reference storage pointing at the correct target","If the target was renamed, update the ref path to the new mount path"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before creating a reference storage, confirm target mount exists\nif _, err := op.GetStorageByMountPath(refMountPath); err != nil {\n    return fmt.Errorf(\"referenced mount %s unavailable: %w\", refMountPath, err)\n}","typeGuard":null,"tryCatchPattern":"if err := op.SaveStorage(ctx, storageAddReq); err != nil {\n    if strings.Contains(err.Error(), \"ref:\") {\n        // surface mount-path guidance to the admin UI\n    }\n}","preventionTips":["Create/verify the target storage before creating any reference to it","When renaming a storage, update or remove storages that reference its mount path","Keep ref mount paths copy-pasted from the storages list to avoid typos"],"tags":["go","storage","mount","reference","config"],"backgroundTag":null,"analyzedSha":"843d9dc8149126976b2625911e45a4d3ffd6f2f5","analyzedAt":"2026-08-15T12:14:11.722Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}