caddyserver/caddy · error

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

Error message

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

What it means

Returned in FileServer.Provision when validating browse sort_options: the second element, when present, must be a sort direction — either asc or desc (sortOrderAsc/sortOrderDesc). The second slot cannot hold another sort key; only one key plus one direction is allowed.

Source

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

			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" {
		// reject paths with Alternate Data Streams (ADS)
		if strings.Contains(r.URL.Path, ":") {
			return caddyhttp.Error(http.StatusBadRequest, fmt.Errorf("illegal ADS path"))
		}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Use only 'asc' or 'desc' as the second option.
2. If you wanted multi-key sorting, remove the extra key — the browse feature supports one key plus direction.
3. Re-run `caddy validate` after fixing.

Example fix

# before
sort_options name size
# after
sort_options name desc

# Pre-deploy check: second sort option, if present, must be asc or desc
second=$(awk '/sort_options/{print $3}' Caddyfile)
if [ -n "$second" ] && [ "$second" != "asc" ] && [ "$second" != "desc" ]; then
  echo "invalid second sort option: $second (want asc|desc)"; exit 1
fi

When it happens

Trigger: sort_options with a second entry that is not 'asc' or 'desc', e.g. `sort_options name size` or `sort_options time namedirfirst`.

Common situations: Attempting to sort by two keys (not supported); typos like 'ascending'/'descending'; assuming the second option is another field name.

Related errors

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