caddyserver/caddy · error

the first option must be one of the following: %s, %s, %s, %

Error message

the first option must be one of the following: %s, %s, %s, %s, but got %s

What it means

Returned in FileServer.Provision when validating browse sort_options: the first element must be one of the four recognized sort keys (name, namedirfirst, size, time — the sortByName/sortByNameDirFirst/sortBySize/sortByTime constants). Any other string in position 0 aborts provisioning.

Source

Thrown at modules/caddyhttp/fileserver/staticfiles.go:254

		if suffix == "" {
			return fmt.Errorf("precompressor does not specify a Suffix value")
		}
		if _, ok := fsrv.precompressors[ae]; ok {
			return fmt.Errorf("precompressor already added: %s", ae)
		}
		if fsrv.precompressors == nil {
			fsrv.precompressors = make(map[string]encode.Precompressed)
		}
		fsrv.precompressors[ae] = p
	}

	if fsrv.Browse != nil {
		// check sort options
		for idx, sortOption := range fsrv.Browse.SortOptions {
			switch idx {
			case 0:
				if sortOption != sortByName && sortOption != sortByNameDirFirst && sortOption != sortBySize && sortOption != sortByTime {
					return fmt.Errorf("the first option must be one of the following: %s, %s, %s, %s, but got %s", sortByName, sortByNameDirFirst, sortBySize, sortByTime, sortOption)
				}
			case 1:
				if sortOption != sortOrderAsc && sortOption != sortOrderDesc {
					return fmt.Errorf("the second option must be one of the following: %s, %s, but got %s", sortOrderAsc, sortOrderDesc, sortOption)
				}
			default:
				return fmt.Errorf("only max 2 sort options are allowed, but got %d", idx+1)
			}
		}
	}

	return nil
}

func (fsrv *FileServer) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error {
	repl := r.Context().Value(caddy.ReplacerCtxKey).(*caddy.Replacer)

	if runtime.GOOS == "windows" {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Put a valid sort key first: name, namedirfirst, size, or time.
2. Put the direction (asc/desc) second, if used.
3. Limit the list to at most 2 entries.
4. Validate with `caddy validate --config Caddyfile` before reloading.

Example fix

# before
sort_options asc name
# after
sort_options name asc

# Pre-deploy check: first sort option must be a known key
valid="name namedirfirst size time"
first=$(awk '/sort_options/{print $2}' Caddyfile)
[[ " $valid " == *" $first "* ]] || { echo "invalid first sort option: $first"; exit 1; }

When it happens

Trigger: Configuring `sort_options` (Caddyfile) or "sort_options" (JSON) under file_server browse where the first entry is not one of: name, namedirfirst, size, time — e.g. 'asc' first, a typo like 'Name', or an unsupported key like 'extension'.

Common situations: Users writing `sort_options asc desc` (order reversed) assuming direction comes first; case mismatches; carrying over sort keys from other software (nginx/fancy-index vocabulary).

Related errors

• the second option must be one of the following: %s, %s, but
• only max 2 sort options are allowed, but got %d
• parsing browse template: %v
• parsing browse template file: %v
• parsing default browse template: %v

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/1fff0c44f47bb5eb. Report an issue: GitHub.