Tencent/WeKnora · error

invalid %s value %q: expected %q or %q

Error message

invalid %s value %q: expected %q or %q

What it means

Thrown by ParseMode in internal/storageurl/mode.go when a client- or config-supplied storage URL mode value is neither empty (default ModeHandle), 'handle', nor 'public'. The raw untrimmed value is echoed in the message; callers fail closed rather than guessing a mode.

Source

Thrown at internal/storageurl/mode.go:77

	if ctx == nil {
		return false
	}
	forced, _ := ctx.Value(forcedHandleKey{}).(bool)
	return forced
}

// ParseMode validates a mode supplied by a client or by configuration. An empty
// value yields ModeHandle so an unset parameter or setting keeps the default.
func ParseMode(raw string) (Mode, error) {
	switch Mode(strings.ToLower(strings.TrimSpace(raw))) {
	case "":
		return ModeHandle, nil
	case ModeHandle:
		return ModeHandle, nil
	case ModePublic:
		return ModePublic, nil
	default:
		return ModeHandle, fmt.Errorf(
			"invalid %s value %q: expected %q or %q", QueryParam, raw, ModeHandle, ModePublic)
	}
}

// badDefault keeps a misconfigured EnvVar to a single log line per distinct bad
// value instead of one per request, while still warning again if an operator
// rolls out a second typo. The value itself is re-read every time so a fix takes
// effect without a restart.
var badDefault struct {
	sync.Mutex
	warned map[string]bool
}

func warnBadDefaultOnce(ctx context.Context, raw string, err error) {
	badDefault.Lock()
	defer badDefault.Unlock()
	if badDefault.warned[raw] {
		return

View on GitHub (pinned to 988cbb0330)

Solutions

1. Set the mode to 'handle' or 'public' (case-insensitive)
2. Remove the parameter entirely to accept the default ModeHandle
3. Fix configuration values that carry typos or extra characters

When it happens

Trigger: Thrown at internal/storageurl/mode.go:77 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/92b7e8cccf486dec. Report an issue: GitHub.