AlistGo/alist · warning

share_id must be 1-32 characters of letters, numbers, unders

Error message

share_id must be 1-32 characters of letters, numbers, underscore or hyphen

What it means

errShareIDInvalid is returned by the share-creation endpoint when a client-supplied share_id fails the regex ^[A-Za-z0-9_-]{1,32}$. Custom share IDs are the URL slug of the share link, so they are restricted to URL-safe characters and a 32-character maximum. The error is predeclared alongside errShareIDExists and validated against shareIDPattern before any DB write.

Source

Thrown at server/handles/share.go:30

	"time"

	"github.com/alist-org/alist/v3/internal/db"
	shareauth "github.com/alist-org/alist/v3/internal/share"

	"github.com/alist-org/alist/v3/internal/fs"
	"github.com/alist-org/alist/v3/internal/model"
	"github.com/alist-org/alist/v3/pkg/utils"
	"github.com/alist-org/alist/v3/pkg/utils/random"
	"github.com/alist-org/alist/v3/server/common"
	"github.com/gin-gonic/gin"
)

const shareAccessTokenLifetime = 24 * time.Hour

var shareIDPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{1,32}$`)

var (
	errShareIDInvalid = errors.New("share_id must be 1-32 characters of letters, numbers, underscore or hyphen")
	errShareIDExists  = errors.New("share link already exists")
)

type CreateShareReq struct {
	Path          string `json:"path" binding:"required"`
	ShareID       string `json:"share_id"`
	Name          string `json:"name"`
	Password      string `json:"password"`
	ExpireAt      string `json:"expire_at"`
	ExpireHours   int64  `json:"expire_hours"`
	AccessLimit   int64  `json:"access_limit"`
	BurnAfterRead *bool  `json:"burn_after_read"`
	AllowPreview  *bool  `json:"allow_preview"`
	AllowDownload *bool  `json:"allow_download"`
}

type UpdateShareReq struct {
	ShareID       string  `json:"share_id" binding:"required"`

View on GitHub (pinned to 843d9dc814)

Solutions

1. Use 1-32 characters of A-Z, a-z, 0-9, '_' or '-' only (e.g. 'holiday-2026')
2. Or omit share_id entirely and let the server generate a random one
3. Client-side: validate with the same regex before submitting

Example fix

// before
{"path": "/photos", "share_id": "my holiday photos!"}
// after
{"path": "/photos", "share_id": "my-holiday-photos"}

var shareIDPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{1,32}$`)
if req.ShareID != "" && !shareIDPattern.MatchString(req.ShareID) {
    return errors.New("share_id must match [A-Za-z0-9_-]{1,32}")
}

func isValidShareID(id string) bool {
    return shareIDPattern.MatchString(id) // ^[A-Za-z0-9_-]{1,32}$
}

When it happens

Trigger: POST to the share-create endpoint with share_id containing spaces, dots, slashes, CJK characters, or any symbol outside letters/digits/underscore/hyphen; or a share_id longer than 32 characters.

Common situations: Users typing a descriptive slug like 'my holiday photos!' or pasting a full path '/share/holiday'; generating IDs from filenames with unicode; length overflow when deriving the ID from a hash.

Related errors

• label name is exists
• file_name must not empty
• invalid file_name
• invalid request
• access_limit must be 0 or greater

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