caddyserver/caddy · error

only max 2 sort options are allowed, but got %d

Error message

only max 2 sort options are allowed, but got %d

What it means

Returned in FileServer.Provision when browse sort_options contains more than two entries. The schema is exactly [sort_key] and optionally [direction]; the loop's default case rejects any third element (idx == 2, reported as idx+1 == 3 options).

Source

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

			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" {
		// reject paths with Alternate Data Streams (ADS)
		if strings.Contains(r.URL.Path, ":") {
			return caddyhttp.Error(http.StatusBadRequest, fmt.Errorf("illegal ADS path"))
		}
		// reject paths with "8.3" short names
		trimmedPath := strings.TrimRight(r.URL.Path, ". ") // Windows ignores trailing dots and spaces, sigh
		if len(path.Base(trimmedPath)) <= 12 && strings.Contains(trimmedPath, "~") {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Trim sort_options to at most two tokens: one sort key, optionally one direction.
2. Delete the extra tokens from the Caddyfile or JSON array.
3. Validate config before reload: `caddy validate --config <file>`.

Example fix

# before
sort_options name asc size
# after
sort_options name asc

# Pre-deploy check: at most 2 tokens after sort_options
n=$(awk '/sort_options/{print NF-1}' Caddyfile)
[ "$n" -le 2 ] || { echo "too many sort_options ($n); max 2"; exit 1; }

When it happens

Trigger: sort_options lists three or more tokens, e.g. `sort_options name asc size`, or a JSON array with 3+ strings under browse.sort_options.

Common situations: Trying to express multi-level sorting; pasting option lists from documentation of other index modules; iterating on config and leaving stale tokens.

Related errors

• the first option must be one of the following: %s, %s, %s, %
• the second option must be one of the following: %s, %s, but
• 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/2ab7c1c186d64080. Report an issue: GitHub.