What causes "object not found" in AlistGo/alist?

Confirm the object exists in the underlying storage (provider console)

AlistGo/alist · error · ObjectNotFound

object not found

Error message

object not found

What it means

ObjectNotFound is the storage-driver-level 'file or folder does not exist' sentinel, defined in internal/errs/object.go. Unlike MetaNotFound (cache miss in the op layer), it is returned when the backing storage itself reports the object is absent. errs.IsObjectNotFound and errs.IsNotFoundError unwrap with pkg/errors Cause and test against it.

Source

Thrown at internal/errs/object.go:10

package errs

import (
	"errors"

	pkgerr "github.com/pkg/errors"
)

var (
	ObjectNotFound = errors.New("object not found")
	NotFolder      = errors.New("not a folder")
	NotFile        = errors.New("not a file")
)

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

View on GitHub (pinned to 843d9dc814)

Solutions

Confirm the object exists in the underlying storage (provider console)
Clear/invalidate the meta cache for the parent path so AList re-lists from the source
Return or map to a 404 response using errs.IsObjectNotFound(err) instead of surfacing a 500
If the object was renamed/moved remotely, refresh the directory listing

Example fix

// before
if err != nil { common.ErrorResp(c, err, 500) }

// after
if errs.IsObjectNotFound(err) {
    common.ErrorResp(c, err, 404)
} else if err != nil {
    common.ErrorResp(c, err, 500)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// optional pre-check via meta cache (cheap) before driver calls
if _, err := op.Get(ctx, path); errs.IsObjectNotFound(err) {
    op.InvalidateCache(parentDir) // refresh and re-check once
}

Type guard

func isObjectNotFound(err error) bool {
    return errs.IsObjectNotFound(err)
}

Try / catch

obj, err := storage.Get(ctx, path)
if err != nil {
    if isObjectNotFound(err) { return nil, errs.NewErr(errs.ObjectNotFound, "%s missing", path) }
    return nil, err
}

Prevention

Map this sentinel to HTTP 404 in handlers
Invalidate the parent's cache after remote deletions
For eventual-consistency stores, add a short read-retry window
Avoid caching negative lookups longer than necessary

When it happens

Trigger: A storage driver's List/Get hitting a missing key (S3 NoSuchKey, 404 from WebDAV/FTP panels) that the driver translates to ObjectNotFound; direct driver calls on paths deleted remotely; ops after a remote deletion not yet reflected in the meta cache.

Common situations: Files deleted upstream while still cached in AList; stale share links; eventual-consistency object stores where a write is listed before it is readable; users pasting old URLs. Standard remedy is to treat as 404 and invalidate the cached entry.

Related errors

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