AlistGo/alist · error · MetaNotFound

meta not found

Error message

meta not found

What it means

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.

Source

Thrown at internal/errs/errors.go:18

package errs

import (
	"errors"
	"fmt"

	pkgerr "github.com/pkg/errors"
)

var (
	NotImplement = errors.New("not implement")
	NotSupport   = errors.New("not support")
	RelativePath = errors.New("access using relative path is not allowed")

	MoveBetweenTwoStorages = errors.New("can't move files between two storages, try to copy")
	UploadNotSupported     = errors.New("upload not supported")

	MetaNotFound     = errors.New("meta not found")
	StorageNotFound  = errors.New("storage not found")
	StreamIncomplete = errors.New("upload/download stream incomplete, possible network issue")
	StreamPeekFail   = errors.New("StreamPeekFail")

	UnknownArchiveFormat      = errors.New("unknown archive format")
	WrongArchivePassword      = errors.New("wrong archive password")
	DriverExtractNotSupported = errors.New("driver extraction not supported")
)

// NewErr wrap constant error with an extra message
// use errors.Is(err1, StorageNotFound) to check if err belongs to any internal error
func NewErr(err error, format string, a ...any) error {
	return fmt.Errorf("%w; %s", err, fmt.Sprintf(format, a...))
}

func IsNotFoundError(err error) bool {
	return errors.Is(pkgerr.Cause(err), ObjectNotFound) || errors.Is(pkgerr.Cause(err), StorageNotFound)
}

View on GitHub (pinned to 843d9dc814)

Solutions

1. Verify the requested path actually exists in the mounted storage (storage driver or web UI) before retrying
2. If the file exists but the error persists, invalidate the meta cache for the storage or restart the service so the tree is rebuilt
3. 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
4. Check that a storage is mounted at the path prefix you are using (see also StorageNotFound)

Example fix

// before
obj, err := op.Get(ctx, path)
if err != nil { return errs.NewErr(err, "get failed") }

// after
obj, err := op.Get(ctx, path)
if errors.Is(errors.Cause(err), errs.MetaNotFound) {
    return errs.NewErr(errs.ObjectNotFound, "path %s not found", path)
}
if err != nil { return errs.NewErr(err, "get failed") }

// before calling fs ops, confirm a storage is mounted for the prefix
if _, _, err := op.GetStorageAndActualPath(path); err != nil { return err }

func isMetaNotFound(err error) bool {
    return err != nil && errors.Is(errors.Cause(err), errs.MetaNotFound)
}

meta, err := op.GetNearestMeta(path)
if err != nil {
    if isMetaNotFound(err) {
        // path unknown yet: create parents, or return 404
    }
    return err // real failure
}

When it happens

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

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

Related errors

• storage not found
• object not found
• directory separator prohibited
• metadata can't be this big
• metadata is too large

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