AlistGo/alist · error

remote_path is required

Error message

remote_path is required

What it means

Returned by Chunker.validateOptions() when the storage's remote_path option is empty or whitespace-only. The chunker driver stores file chunks at a remote path on another alist storage; without it there is nowhere to place chunks, so initialization fails fast.

Source

Thrown at drivers/chunker/util.go:28

	"path"
	"regexp"
	"sort"
	"strconv"
	"strings"
	"time"

	"github.com/alist-org/alist/v3/internal/errs"
	"github.com/alist-org/alist/v3/internal/fs"
	"github.com/alist-org/alist/v3/internal/model"
	"github.com/alist-org/alist/v3/internal/op"
	"github.com/alist-org/alist/v3/internal/stream"
	"github.com/alist-org/alist/v3/pkg/http_range"
	"github.com/alist-org/alist/v3/pkg/utils"
)

func (d *Chunker) validateOptions() error {
	if strings.TrimSpace(d.RemotePath) == "" {
		return errors.New("remote_path is required")
	}
	if d.ChunkSize <= 0 {
		return errors.New("chunk_size must be positive")
	}
	switch d.MetaFormat {
	case "simplejson", "none":
	default:
		return fmt.Errorf("unsupported meta_format: %s", d.MetaFormat)
	}
	switch d.HashType {
	case "none", "md5", "sha1":
	default:
		return fmt.Errorf("unsupported hash_type: %s", d.HashType)
	}
	if d.MetaFormat == "none" && d.HashType != "none" {
		return fmt.Errorf("hash_type %q requires meta_format=simplejson", d.HashType)
	}
	return nil

View on GitHub (pinned to 843d9dc814)

Solutions

1. Set remote_path in the storage addition to an absolute path on a mounted storage, e.g. /local/chunker-store
2. Ensure the referenced mount path exists and the underlying storage is healthy
3. Save and reload the storage so validateOptions passes

Example fix

// before
addition: { remote_path: "" }
// after
addition: { remote_path: "/local-drive/chunker-store" }

func validChunkerOpts(remotePath string) bool { return strings.TrimSpace(remotePath) != "" }

if err := d.validateOptions(); err != nil && strings.Contains(err.Error(), "remote_path is required") { /* prompt user for remote_path, then re-save storage */ }

When it happens

Trigger: Creating or updating a Chunker storage whose RemotePath field is blank; loading a previously saved storage where remote_path was never set (e.g. migrated config).

Common situations: New storage created without filling remote_path; config edited via API that clears the field; spaces-only value pasted accidentally.

Related errors

• chunk_size must be positive
• directory separator prohibited
• name token must come before chunk token
• pattern must contain one name token: {name}
• pattern must contain exactly one name token: {name}

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