{"record":{"id":"da1c34c62f98a134","repo":"AlistGo/alist","slug":"failed-to-convert-path-to-remote-path-w-da1c34","errorCode":null,"errorMessage":"failed to convert path to remote path: %w","messagePattern":"failed to convert path to remote path: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/crypt/driver.go","lineNumber":247,"sourceCode":"\t\t\tlog.Warnf(\"DecryptDirName failed for %s ,will use original name, err:%s\", path, err)\n\t\t\tname = remoteObj.GetName()\n\t\t}\n\t}\n\tobj := &model.Object{\n\t\tPath:     path,\n\t\tName:     name,\n\t\tSize:     size,\n\t\tModified: remoteObj.ModTime(),\n\t\tIsFolder: remoteObj.IsDir(),\n\t}\n\treturn obj, nil\n\t//return nil, errs.ObjectNotFound\n}\n\nfunc (d *Crypt) Link(ctx context.Context, file model.Obj, args model.LinkArgs) (*model.Link, error) {\n\tdstDirActualPath, err := d.getActualPathForRemote(file.GetPath(), false)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to convert path to remote path: %w\", err)\n\t}\n\tremoteLink, remoteFile, err := op.Link(ctx, d.remoteStorage, dstDirActualPath, args)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif remoteLink.RangeReadCloser == nil && remoteLink.MFile == nil && len(remoteLink.URL) == 0 {\n\t\treturn nil, fmt.Errorf(\"the remote storage driver need to be enhanced to support encrytion\")\n\t}\n\tremoteFileSize := remoteFile.GetSize()\n\tremoteClosers := utils.EmptyClosers()\n\trangeReaderFunc := func(ctx context.Context, underlyingOffset, underlyingLength int64) (io.ReadCloser, error) {\n\t\tlength := underlyingLength\n\t\tif underlyingLength >= 0 && underlyingOffset+underlyingLength >= remoteFileSize {\n\t\t\tlength = -1\n\t\t}\n\t\trrc := remoteLink.RangeReadCloser\n\t\tif len(remoteLink.URL) > 0 {","sourceCodeStart":229,"sourceCodeEnd":265,"githubUrl":"https://github.com/AlistGo/alist/blob/843d9dc8149126976b2625911e45a4d3ffd6f2f5/drivers/crypt/driver.go#L229-L265","documentation":"Thrown by Crypt.Link when translating the user-visible (decrypted) file path to the remote storage's internal actual path fails. getActualPathForRemote encrypts the directory/file names, joins them onto RemotePath, then calls op.GetStorageAndActualPath to split the result into storage + actual path. Any failure there — most commonly the storage mount no longer resolving — surfaces wrapped in this message, aborting the link/download operation before the remote link is even requested.","triggerScenarios":"Requesting a download link (Link) for a file inside the crypt mount when the underlying remote storage has been unmounted/deleted/renamed since the crypt storage was initialized, or when the encrypted path fails to map under the mounted storage path (RemotePath drift, cached stale storage reference after restart).","commonSituations":"Underlying storage removed while crypt storage still references it; AList restart where d.remoteStorage holds a stale mount; RemotePath pointing at a subfolder that was moved on the remote; path containing characters that after encryption break the storage-path split.","solutions":["Confirm the underlying storage still exists and is mounted at the path RemotePath points to; re-add or fix it if missing","Refresh/re-save the crypt storage so Init re-resolves d.remoteStorage against current mounts","Check logs for the wrapped op.GetStorageAndActualPath error to identify whether the storage root or the sub-path failed","Avoid renaming the underlying storage's mount path; if renamed, update RemotePath accordingly"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before requesting a link, confirm the crypt storage's remote still resolves\nif _, _, err := op.GetStorageAndActualPath(remotePathOfCryptStorage); err != nil {\n    return fmt.Errorf(\"underlying storage unavailable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"link, err := cryptDriver.Link(ctx, file, args)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to convert path to remote path\") {\n        // storage-mount drift: surface a config error, don't retry the download\n        return nil, fmt.Errorf(\"crypt remote storage misconfigured: %w\", err)\n    }\n    return nil, err\n}","preventionTips":["Monitor the underlying storage's health; disable the crypt mount when the base storage is down","Don't rename underlying mount paths without updating RemotePath","On AList restart, verify crypt storages re-init successfully before serving downloads"],"tags":["crypt","download","storage-mount","path-resolution"],"backgroundTag":null,"analyzedSha":"843d9dc8149126976b2625911e45a4d3ffd6f2f5","analyzedAt":"2026-08-15T12:14:11.722Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}