unrecognized poison_pill_handling %q: valid values are %q an

Error message

unrecognized poison_pill_handling %q: valid values are %q and %q

What it means

validatePoisonHandling rejects an unrecognized value for the poison_pill_handling option. Only empty (default), 'fail' (PoisonFail), and 'drop' (PoisonDrop) are accepted; anything else would otherwise be silently treated as the default, so the whole-config Validate fails fast instead.

Source

Thrown at internal/storage/elasticsearch/config/config.go:549

}

// EffectivePoisonHandling resolves the poison-pill policy Jaeger should use: the
// explicit PoisonPillHandling from config, or PoisonFail when it is unset.
func (c *Configuration) EffectivePoisonHandling() PoisonHandling {
	if c.PoisonPillHandling != "" {
		return c.PoisonPillHandling
	}
	return PoisonFail
}

// validatePoisonHandling rejects an unrecognized poison_pill_handling. An empty
// value is allowed and resolves to the default (PoisonFail).
func validatePoisonHandling(mode PoisonHandling) error {
	switch mode {
	case "", PoisonFail, PoisonDrop:
		return nil
	default:
		return fmt.Errorf("unrecognized poison_pill_handling %q: valid values are %q and %q", mode, PoisonFail, PoisonDrop)
	}
}

// validateWriteMode rejects an unrecognized write_mode. An empty value is allowed
// and resolves to the default (WriteModeAsync). It mirrors validateLogLevel:
// write_mode carries no govalidator struct tag, so the whole-config Validate must
// check it explicitly.
func validateWriteMode(mode WriteMode) error {
	switch mode {
	case "", WriteModeAsync, WriteModeSync:
		return nil
	default:
		return fmt.Errorf("unrecognized write_mode %q: valid values are %q and %q", mode, WriteModeAsync, WriteModeSync)
	}
}

// validateLogLevel rejects an unrecognized log_level. An empty value is allowed
// and means no client logging is attached.

View on GitHub (pinned to 806f444784)

Solutions

Set poison_pill_handling to exactly 'fail' or 'drop' (or remove the key to get the default 'fail').
Check for typos, casing, and whitespace in the config value; quote the string in YAML to avoid parser mangling.
Check the govalidator/enum documentation for the option to see the accepted literals.
If you intended a behavior that isn't fail/drop, implement it upstream or handle it outside the config instead of inventing a keyword.

Example fix

# before
poison_pill_handling: Drop
# after
poison_pill_handling: drop

Defensive patterns

Strategy: validation

Validate before calling

func validPoisonHandling(s string) bool {
    switch s {
    case "", "fail", "drop":
        return true
    }
    return false
}
// call before assigning the config field

Try / catch

if err := cfg.Validate(); err != nil {
    if strings.Contains(err.Error(), "unrecognized poison_pill_handling") {
        log.Printf("poison_pill_handling must be exactly 'fail' or 'drop'; got %q", cfg.PoisonHandling)
    }
    return err
}

Prevention

Only use the documented literals: 'fail' or 'drop'.
Quote enum strings in YAML and strip surrounding whitespace.
Lowercase-check values if sourcing from case-insensitive env vars.
Validate the whole config in CI before rollout.

When it happens

Trigger: Configuring es_index_cleaner / rollover poison pill handling with a misspelled or unsupported value (e.g. 'retry', 'ignore', 'FAIL' if matching is case-sensitive, 'delete') via config file or env var.

Common situations: Typo in YAML ('poision_pill_handling: drop' won't even bind; 'drop ' with trailing space, or 'Drop' wrong case); copying a value from an old document; using a plausible value that was never implemented.

Related errors

AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/3255564ecc34ac0a. Report an issue: GitHub.