block/buzz · error · anyhow::Error

--channel requires --relay-key or BUZZ_RELAY_PRIVATE_KEY

Error message

--channel requires --relay-key or BUZZ_RELAY_PRIVATE_KEY

What it means

reconcile-channels republishes authoritative channel events. Without --channel it may fall back to an ephemeral key (with warnings) because it only bootstraps missing snapshots, but with --channel it force-replaces an existing channel's events — signing those with a throwaway key would make them unverifiable. The CLI therefore refuses when --channel is given and neither --relay-key nor BUZZ_RELAY_PRIVATE_KEY supplies the stable signing key.

Solutions

1. Pass the relay's secret key explicitly: buzz-admin reconcile-channels --channel <uuid> --relay-key <64-hex-secret>.
2. Or export BUZZ_RELAY_PRIVATE_KEY with the same secret the relay signs with, then re-run.
3. If you only meant to backfill missing events, drop --channel and let the ephemeral-key warning path run (bootstrap only).
4. Verify the key parses beforehand (see the 'invalid relay key' guidance) to avoid a second failure.

Example fix

# before
buzz-admin reconcile-channels --channel 6f1c...  # -> --channel requires --relay-key or BUZZ_RELAY_PRIVATE_KEY
# after
buzz-admin reconcile-channels --channel 6f1c... --relay-key "$BUZZ_RELAY_PRIVATE_KEY"

# enforce the flag invariant before invoking the CLI
if [ "$1" = "--channel" ] || [[ " $* " == *" --channel "* ]]; then
  [ -n "${RELAY_KEY:-}${BUZZ_RELAY_PRIVATE_KEY:-}" ] || { echo 'channel reconcile needs a relay key' >&2; exit 3; }
fi

When it happens

Trigger: Running `buzz-admin reconcile-channels --channel <uuid>` with no --relay-key flag and no BUZZ_RELAY_PRIVATE_KEY in the environment.

Common situations: Operators copying the documented bootstrap command (no key) and adding --channel; CI jobs that only set DATABASE_URL/RELAY_URL.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• invalid --channel UUID
• channel not found in community
• invalid relay key
• sign kind:39000
• BUZZ_RELAY_PRIVATE_KEY is required for…

AI-assisted analysis of block/buzz@ef2aa1ae38 (2026-08-20). Data as JSON: /api/errors/0e806916c837fdbe. Report an issue: GitHub.

Appendix: source

Thrown at crates/buzz-admin/src/main.rs:637

    Ok(TenantContext::resolved(record.id, record.host))
}

async fn reconcile_channels(
    channel_arg: Option<String>,
    relay_key_arg: Option<String>,
) -> Result<()> {
    use buzz_core::kind::KIND_NIP29_GROUP_ADMINS;
    use buzz_db::event::EventQuery;

    let db = connect_db().await?;

    // Resolve relay signing key: arg > env > ephemeral. Force-republish must
    // never use an ephemeral key because it replaces an existing authoritative
    // snapshot.
    let configured_relay_key =
        relay_key_arg.or_else(|| std::env::var("BUZZ_RELAY_PRIVATE_KEY").ok());
    if channel_arg.is_some() && configured_relay_key.is_none() {
        return Err(anyhow::anyhow!(
            "--channel requires --relay-key or BUZZ_RELAY_PRIVATE_KEY"
        ));
    }
    let relay_keys = match configured_relay_key {
        Some(key_hex) => {
            Keys::parse(&key_hex).map_err(|e| anyhow::anyhow!("invalid relay key: {e}"))?
        }
        None => {
            let k = Keys::generate();
            eprintln!(
                "Warning: no relay key provided — using ephemeral key {}",
                k.public_key().to_hex()
            );
            eprintln!("Events signed with this key won't be verifiable after this run.");
            eprintln!("Pass --relay-key or set BUZZ_RELAY_PRIVATE_KEY for production use.");
            k
        }
    };

View on GitHub (pinned to ef2aa1ae38)