{"record":{"id":"bb80ff11e173dfc3","repo":"AlistGo/alist","slug":"meta-not-found","errorCode":null,"errorMessage":"meta not found","messagePattern":"meta not found","errorType":"exception","errorClass":"MetaNotFound","httpStatus":null,"severity":"error","filePath":"internal/errs/errors.go","lineNumber":18,"sourceCode":"package errs\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\n\tpkgerr \"github.com/pkg/errors\"\n)\n\nvar (\n\tNotImplement = errors.New(\"not implement\")\n\tNotSupport   = errors.New(\"not support\")\n\tRelativePath = errors.New(\"access using relative path is not allowed\")\n\n\tMoveBetweenTwoStorages = errors.New(\"can't move files between two storages, try to copy\")\n\tUploadNotSupported     = errors.New(\"upload not supported\")\n\n\tMetaNotFound     = errors.New(\"meta not found\")\n\tStorageNotFound  = errors.New(\"storage not found\")\n\tStreamIncomplete = errors.New(\"upload/download stream incomplete, possible network issue\")\n\tStreamPeekFail   = errors.New(\"StreamPeekFail\")\n\n\tUnknownArchiveFormat      = errors.New(\"unknown archive format\")\n\tWrongArchivePassword      = errors.New(\"wrong archive password\")\n\tDriverExtractNotSupported = errors.New(\"driver extraction not supported\")\n)\n\n// NewErr wrap constant error with an extra message\n// use errors.Is(err1, StorageNotFound) to check if err belongs to any internal error\nfunc NewErr(err error, format string, a ...any) error {\n\treturn fmt.Errorf(\"%w; %s\", err, fmt.Sprintf(format, a...))\n}\n\nfunc IsNotFoundError(err error) bool {\n\treturn errors.Is(pkgerr.Cause(err), ObjectNotFound) || errors.Is(pkgerr.Cause(err), StorageNotFound)\n}","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/AlistGo/alist/blob/843d9dc8149126976b2625911e45a4d3ffd6f2f5/internal/errs/errors.go#L1-L36","documentation":"MetaNotFound is a sentinel error in internal/errs/errors.go indicating that no cached metadata (a model.Obj plus its tree) exists for a requested path in the op layer (internal/op/meta.go). It is the canonical 'path does not exist yet' signal returned when the object tree lookup misses. Handlers in server/handles and server/ftp explicitly test for it with errors.Is(errors.Cause(err), errs.MetaNotFound) to distinguish a benign miss (tolerated during upload/mkdir into a new path) from real failures.","triggerScenarios":"Calling op meta/path resolution for a path that was never cached: after storage mount, after cache invalidation, or when the file simply does not exist. API calls such as /api/fs/get, /api/fs/list, mkdir-into-missing-parent, and upload middlewares (server/middlewares/down.go, fsup.go) hit it when the path's meta record is absent.","commonSituations":"Requesting a file or directory that does not exist; querying immediately after a storage was added or its cache cleared (op.InvalidateCache); racing a concurrent deletion; guest users probing paths they cannot see. Often appears as a benign branch in upload/mkdir flows rather than a hard failure.","solutions":["Verify the requested path actually exists in the mounted storage (storage driver or web UI) before retrying","If the file exists but the error persists, invalidate the meta cache for the storage or restart the service so the tree is rebuilt","In handler code, treat this error as 404 rather than 500 — mirror the errors.Is(errors.Cause(err), errs.MetaNotFound) pattern used in server/handles","Check that a storage is mounted at the path prefix you are using (see also StorageNotFound)"],"exampleFix":"// before\nobj, err := op.Get(ctx, path)\nif err != nil { return errs.NewErr(err, \"get failed\") }\n\n// after\nobj, err := op.Get(ctx, path)\nif errors.Is(errors.Cause(err), errs.MetaNotFound) {\n    return errs.NewErr(errs.ObjectNotFound, \"path %s not found\", path)\n}\nif err != nil { return errs.NewErr(err, \"get failed\") }","handlingStrategy":"try-catch","validationCode":"// before calling fs ops, confirm a storage is mounted for the prefix\nif _, _, err := op.GetStorageAndActualPath(path); err != nil { return err }","typeGuard":"func isMetaNotFound(err error) bool {\n    return err != nil && errors.Is(errors.Cause(err), errs.MetaNotFound)\n}","tryCatchPattern":"meta, err := op.GetNearestMeta(path)\nif err != nil {\n    if isMetaNotFound(err) {\n        // path unknown yet: create parents, or return 404\n    }\n    return err // real failure\n}","preventionTips":["Check mounted storages' base paths before issuing requests","Invalidate meta cache after remote out-of-band changes","Treat MetaNotFound as 404 in handlers, never 500","When uploading new files, expect this error for new parents and handle mkdir-then-retry"],"tags":["filesystem","metadata","cache","not-found"],"backgroundTag":null,"analyzedSha":"843d9dc8149126976b2625911e45a4d3ffd6f2f5","analyzedAt":"2026-08-15T12:14:11.722Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}