What causes "ref: %w" in AlistGo/alist?

Verify the exact mount path in the ref: remark matches an existing storage's mount path (copy-paste it from the storages list)

AlistGo/alist · error

ref: %w

Error message

ref: %w

What it means

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".

Source

Thrown at internal/op/storage.go:140

			storagesMap.Store(driverStorage.MountPath, storageDriver)
		}
	}()
	// Unmarshal Addition
	err = utils.Json.UnmarshalFromString(driverStorage.Addition, storageDriver.GetAddition())
	if err == nil {
		if ref, ok := storageDriver.(driver.Reference); ok {
			if strings.HasPrefix(driverStorage.Remark, "ref:/") {
				refMountPath := driverStorage.Remark
				i := strings.Index(refMountPath, "\n")
				if i > 0 {
					refMountPath = refMountPath[4:i]
				} else {
					refMountPath = refMountPath[4:]
				}
				var refStorage driver.Driver
				refStorage, err = GetStorageByMountPath(refMountPath)
				if err != nil {
					err = fmt.Errorf("ref: %w", err)
				} else {
					err = ref.InitReference(refStorage)
					if err != nil && errs.IsNotSupportError(err) {
						err = fmt.Errorf("ref: storage is not %s", storageDriver.Config().Name)
					}
				}
			}
		}
	}
	if err == nil {
		err = storageDriver.Init(ctx)
	}
	storagesMap.Store(driverStorage.MountPath, storageDriver)
	if err != nil {
		driverStorage.SetStatus(err.Error())
		err = errors.Wrap(err, "failed init storage")
	} else {
		driverStorage.SetStatus(WORK)

View on GitHub (pinned to 843d9dc814)

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

Defensive patterns

Strategy: validation

Validate before calling

// before creating a reference storage, confirm target mount exists
if _, err := op.GetStorageByMountPath(refMountPath); err != nil {
    return fmt.Errorf("referenced mount %s unavailable: %w", refMountPath, err)
}

Try / catch

if err := op.SaveStorage(ctx, storageAddReq); err != nil {
    if strings.Contains(err.Error(), "ref:") {
        // surface mount-path guidance to the admin UI
    }
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/77794ceda69d87b6. Report an issue: GitHub.