AlistGo/alist · error

the remote storage driver need to be enhanced to support enc

Error message

the remote storage driver need to be enhanced to support encrytion

What it means

Returned by Crypt.Link when the resolved remote link provides none of the three access mechanisms the crypt reader needs: no RangeReadCloser, no MFile, and no URL. Crypt decryption requires random-access reads (it seeks to encrypted blocks and streams through the cipher), so a remote driver that only returns an empty Link cannot be used for transparent decryption. This is a hard capability gap, not a transient failure.

Source

Thrown at drivers/crypt/driver.go:255

		Modified: remoteObj.ModTime(),
		IsFolder: remoteObj.IsDir(),
	}
	return obj, nil
	//return nil, errs.ObjectNotFound
}

func (d *Crypt) Link(ctx context.Context, file model.Obj, args model.LinkArgs) (*model.Link, error) {
	dstDirActualPath, err := d.getActualPathForRemote(file.GetPath(), false)
	if err != nil {
		return nil, fmt.Errorf("failed to convert path to remote path: %w", err)
	}
	remoteLink, remoteFile, err := op.Link(ctx, d.remoteStorage, dstDirActualPath, args)
	if err != nil {
		return nil, err
	}

	if remoteLink.RangeReadCloser == nil && remoteLink.MFile == nil && len(remoteLink.URL) == 0 {
		return nil, fmt.Errorf("the remote storage driver need to be enhanced to support encrytion")
	}
	remoteFileSize := remoteFile.GetSize()
	remoteClosers := utils.EmptyClosers()
	rangeReaderFunc := func(ctx context.Context, underlyingOffset, underlyingLength int64) (io.ReadCloser, error) {
		length := underlyingLength
		if underlyingLength >= 0 && underlyingOffset+underlyingLength >= remoteFileSize {
			length = -1
		}
		rrc := remoteLink.RangeReadCloser
		if len(remoteLink.URL) > 0 {
			var converted, err = stream.GetRangeReadCloserFromLink(remoteFileSize, remoteLink)
			if err != nil {
				return nil, err
			}
			rrc = converted
		}
		if rrc != nil {
			remoteReader, err := rrc.RangeRead(ctx, http_range.Range{Start: underlyingOffset, Length: length})

View on GitHub (pinned to 843d9dc814)

Solutions

1. Use crypt with a well-supported underlying driver (local, Onedrive, GoogleDrive, S3, etc.) whose Link returns a URL or RangeReadCloser
2. Update AList and the underlying driver to a version that populates Link.URL or Link.RangeReadCloser
3. If the underlying driver is custom, enhance it to return at least a URL or implement RangeReadCloser
4. As a workaround, download directly from the underlying mount (unencrypted) instead of through the crypt mount

// Probe capability once: request a Link for a small file on the underlying storage and check
// that URL, MFile, or RangeReadCloser is populated before mounting crypt on top of it.

func supportsCryptLink(l *model.Link) bool {
    return l.RangeReadCloser != nil || l.MFile != nil || len(l.URL) > 0
}

if err != nil {
    if strings.Contains(err.Error(), "need to be enhanced to support encrytion") {
        // permanent capability gap: switch underlying driver, retrying is pointless
        return fmt.Errorf("underlying driver cannot serve range reads for crypt; use a different storage driver")
    }
    return err
}

When it happens

Trigger: Downloading a file through the crypt mount where the underlying driver's Link returns an empty *model.Link — e.g. a driver that has not implemented Link fully, returns only header-based links without a RangeReadCloser, or a driver whose link type is unsupported (some proxy/abstract drivers). op.Link succeeded but produced a Link with all three fields empty.

Common situations: Using crypt on top of a storage driver that only supports proxy-only or partial link responses; third-party driver plugins not implementing RangeReadCloser or URL; drivers that rely solely on a Header-only link for redirect scenarios where URL is intentionally blank.

Related errors

• failed to convert path to remote path: %w
• open download file failed: %w
• missing cookie or qrcode account
• server returns no url
• empty download url

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