Unknown scheduling policy '{s}', try active,essential,pause,

Error message

Unknown scheduling policy '{s}', try active,essential,pause,stop

What it means

storcon_cli parses its scheduling-policy CLI argument through a FromStr impl that accepts exactly four lowercase strings: active, essential, pause, stop. Any other input fails during argument parsing, before any request reaches the storage controller. The four values map to ShardSchedulingPolicy variants Active, Essential, Pause, Stop.

Source

Thrown at control_plane/storcon_cli/src/main.rs:392

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        SkSchedulingPolicy::from_str(s).map(Self)
    }
}

#[derive(Debug, Clone)]
struct ShardSchedulingPolicyArg(ShardSchedulingPolicy);

impl FromStr for ShardSchedulingPolicyArg {
    type Err = anyhow::Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "active" => Ok(Self(ShardSchedulingPolicy::Active)),
            "essential" => Ok(Self(ShardSchedulingPolicy::Essential)),
            "pause" => Ok(Self(ShardSchedulingPolicy::Pause)),
            "stop" => Ok(Self(ShardSchedulingPolicy::Stop)),
            _ => Err(anyhow::anyhow!(
                "Unknown scheduling policy '{s}', try active,essential,pause,stop"
            )),
        }
    }
}

#[derive(Debug, Clone)]
struct NodeAvailabilityArg(NodeAvailabilityWrapper);

impl FromStr for NodeAvailabilityArg {
    type Err = anyhow::Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "active" => Ok(Self(NodeAvailabilityWrapper::Active)),
            "offline" => Ok(Self(NodeAvailabilityWrapper::Offline)),
            _ => Err(anyhow::anyhow!("Unknown availability state '{s}'")),
        }

View on GitHub (pinned to 8f60b04da4)

Solutions

Re-run with one of the exact lowercase values: active, essential, pause, stop
Run storcon_cli <subcommand> --help to see the accepted values for the flag
If you meant node up/down state, use the availability argument (active, offline) instead of the scheduling policy argument

Example fix

# before
storcon_cli node configure --node-id 1 --scheduling Draining
# after
storcon_cli node configure --node-id 1 --scheduling pause

Defensive patterns

Strategy: validation

Validate before calling

const VALID_SCHEDULING: &[&str] = &["active", "essential", "pause", "stop"];

fn validate_scheduling(value: &str) -> Result<(), String> {
    if VALID_SCHEDULING.contains(&value) {
        Ok(())
    } else {
        Err(format!("invalid scheduling policy '{value}', expected one of {VALID_SCHEDULING:?}"))
    }
}
// call before spawning storcon_cli
validate_scheduling(&policy)?;

Type guard

fn is_valid_scheduling_policy(s: &str) -> bool {
    matches!(s, "active" | "essential" | "pause" | "stop")
}

Prevention

Keep the allowed vocabulary in one shared constant next to the code that builds storcon_cli commands
Never let scheduling and availability vocabularies mix; assert the flag name and value set together
Fail fast in scripts: validate arguments before running any mutating storcon_cli command

When it happens

Trigger: Running a storcon_cli subcommand that takes a scheduling policy (e.g. node configure with a --scheduling-style flag) with a misspelled, capitalized, or out-of-vocabulary value such as 'Active', 'draining', or 'filling'. Clap surfaces the anyhow error from ShardSchedulingPolicyArg::from_str verbatim.

Common situations: Typos or wrong casing; using vocabulary from other Neon components (pageserver 'draining'/'filling' scheduling states) that is not valid here; confusing scheduling policy with node availability (active/offline) and passing the wrong one.

Related errors

AI-assisted analysis of neondatabase/neon@8f60b04da4 (2026-08-16). Data as JSON: /api/errors/95698f27af5b3222. Report an issue: GitHub.