AlistGo/alist · error

chunk_size must be positive

Error message

chunk_size must be positive

What it means

Returned by Chunker.validateOptions() when chunk_size is zero or negative. Chunk size determines how files are split into remote objects; a non-positive value makes chunk math impossible, so the driver rejects it at init.

Source

Thrown at drivers/chunker/util.go:31

	"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
}

func (d *Chunker) configuredRemotePaths() []string {

View on GitHub (pinned to 843d9dc814)

Solutions

1. Set chunk_size to a positive byte count (e.g. 5368709120 for 5 GiB) in the storage addition
2. Keep the value within what the backing storage supports for a single object
3. Save and re-open the storage to confirm validation passes

Example fix

// before
addition: { remote_path: "/store", chunk_size: 0 }
// after
addition: { remote_path: "/store", chunk_size: 5368709120 }

func validChunkSize(n int64) bool { return n > 0 }
// e.g. 5 GiB
if !validChunkSize(addition.ChunkSize) { return errors.New("chunk_size must be a positive byte count") }

null

if err := d.validateOptions(); err != nil && strings.Contains(err.Error(), "chunk_size must be positive") { /* set chunk_size:5368709120 and re-save */ }

When it happens

Trigger: Creating a Chunker storage with chunk_size unset (zero default after JSON omission) or manually entering a negative/zero value; older configs where the field did not exist.

Common situations: Config written via API/template that omits chunk_size; user assumes an optional field and leaves 0; unit confusion (entering 0 thinking it means 'auto').

Related errors

• remote_path is required
• 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/d22d19c3635b9bb7. Report an issue: GitHub.