AlistGo/alist · error

EncryptedSuffix is Illegal

Error message

EncryptedSuffix is Illegal

What it means

Initialization validation in the Crypt driver. The encrypted_suffix option (e.g. .bin) must match ^[.][A-Za-z0-9-_]{2,}$: begin with a dot, then at least two characters drawn from letters, digits, hyphen, or underscore. Validation runs before the .bin default is applied, so anything failing the regex — including an empty value — aborts Init with this message.

Source

Thrown at drivers/crypt/driver.go:57

func (d *Crypt) GetAddition() driver.Additional {
	return &d.Addition
}

func (d *Crypt) Init(ctx context.Context) error {
	//obfuscate credentials if it's updated or just created
	err := d.updateObfusParm(&d.Password)
	if err != nil {
		return fmt.Errorf("failed to obfuscate password: %w", err)
	}
	err = d.updateObfusParm(&d.Salt)
	if err != nil {
		return fmt.Errorf("failed to obfuscate salt: %w", err)
	}

	isCryptExt := regexp.MustCompile(`^[.][A-Za-z0-9-_]{2,}$`).MatchString
	if !isCryptExt(d.EncryptedSuffix) {
		return fmt.Errorf("EncryptedSuffix is Illegal")
	}
	d.FileNameEncoding = utils.GetNoneEmpty(d.FileNameEncoding, "base64")
	d.EncryptedSuffix = utils.GetNoneEmpty(d.EncryptedSuffix, ".bin")

	op.MustSaveDriverStorage(d)

	//need remote storage exist
	storage, err := fs.GetStorage(d.RemotePath, &fs.GetStoragesArgs{})
	if err != nil {
		return fmt.Errorf("can't find remote storage: %w", err)
	}
	d.remoteStorage = storage

	p, _ := strings.CutPrefix(d.Password, obfuscatedPrefix)
	p2, _ := strings.CutPrefix(d.Salt, obfuscatedPrefix)
	config := configmap.Simple{
		"password":                  p,
		"password2":                 p2,

View on GitHub (pinned to 843d9dc814)

Solutions

1. Use a suffix matching the pattern: leading dot plus 2+ characters of letters/digits/hyphen/underscore — ".bin", ".enc", ".c1"
2. Avoid additional dots or special characters in the suffix
3. Leave the field untouched to inherit the ".bin" default rather than blanking it

Example fix

// before
"encrypted_suffix": ".bin.enc"

// after
"encrypted_suffix": ".bin"

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

if !encryptedSuffixRe.MatchString(cfg.EncryptedSuffix) {
    return fmt.Errorf("encrypted_suffix %q must be a dot followed by 2+ of [A-Za-z0-9-_]", cfg.EncryptedSuffix)
}

func isValidEncryptedSuffix(s string) bool {
    return regexp.MustCompile(`^[.][A-Za-z0-9-_]{2,}$`).MatchString(s)
}

if err := cryptStorage.Init(ctx); err != nil {
    if strings.Contains(err.Error(), "EncryptedSuffix is Illegal") {
        cfg.EncryptedSuffix = ".bin" // reset to default and re-init once
    }
}

When it happens

Trigger: Setting encrypted_suffix to a value that is empty, lacks the leading dot ("bin"), is too short (".b"), or contains characters outside [A-Za-z0-9-_] (".bin.enc", ".b!n", ".bin files"). Note the default ".bin" comes from the Addition tag, so blank only fails when the field is explicitly cleared/emptied in a context where the default was not re-applied.

Common situations: Trying a multi-part suffix like ".enc.gz" (dot is not allowed after the first); using a one-character suffix like ".x"; copying suffix conventions from rclone crypt where different rules apply; explicit empty value from API-driven storage creation.

Related errors

• failed to obfuscate password: %w
• failed to obfuscate salt: %w
• unsupported meta_format: %s
• unsupported hash_type: %s
• hash_type %q requires meta_format=simplejson

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