What causes "please specify one of `--faucet` or `--genesis`." in linera-io/linera-protocol?

Pass a faucet URL: `--faucet https:// `

please specify one of `--faucet` or `--genesis`.

Error message

please specify one of `--faucet` or `--genesis`.

What it means

This command path builds a GenesisConfig from exactly one source: a local genesis file (`--genesis <path>`, read via `util::read_json`) or a faucet URL (`--faucet <url>`, fetched and validated via `faucet.version_info()`). The `(None, None)` arm of the match bails when neither flag is supplied. If both are supplied, the `--genesis` file takes precedence.

Source

Thrown at linera-service/src/cli/main.rs:2668

                         switch to another chain with `wallet set-default` first"
                    );
                }
                wallet
                    .remove(*chain_id)?
                    .ok_or_else(|| anyhow::anyhow!("nonexistent chain `{chain_id}`"))?;
                info!("Chain forgotten in {} ms", start_time.elapsed().as_millis());
                Ok(0)
            }

            WalletCommand::Init {
                genesis_config_path,
                faucet,
                testing_prng_seed,
            } => {
                let start_time = Instant::now();
                let genesis_config: GenesisConfig = match (genesis_config_path, faucet) {
                    (None, None) => {
                        anyhow::bail!("please specify one of `--faucet` or `--genesis`.")
                    }
                    (Some(genesis_config_path), _) => util::read_json(genesis_config_path)?,
                    (None, Some(url)) => {
                        let faucet = cli_wrappers::Faucet::new(url.clone());
                        let version_info = faucet
                            .version_info()
                            .await
                            .context("Failed to obtain version information from the faucet")?;
                        if !version_info.is_compatible_with(&linera_version::VERSION_INFO) {
                            warn!(
                                "\
Make sure to use a Linera client compatible with this network.
--- Faucet info ---\
{}\
-------------------
--- This binary ---\
{}\
-------------------",

View on GitHub (pinned to 6c226ddcb3)

Solutions

Pass a faucet URL: `--faucet https://<faucet-host>`
Or pass a local genesis file: `--genesis <path/to/genesis.json>`
If both are set, remove the one you do not want (genesis wins over faucet)

Example fix

# before
linera net up --with-faucet   # no --faucet/--genesis -> bail

# after
linera net up --faucet https://faucet.testnet.linera.net --with-faucet

Defensive patterns

Strategy: validation

Validate before calling

// Validate before invoking the command.
let genesis_source = match (genesis_config_path, faucet_url) {
    (Some(p), _) => GenesisSource::File(p),
    (None, Some(u)) => GenesisSource::Faucet(u),
    (None, None) => anyhow::bail!("provide either --faucet or --genesis"),
};

Prevention

Make your launcher fail fast on missing flags instead of relying on the CLI's late bail
When configs are supposed to supply the faucet URL, assert the resolved value is non-empty before spawn
Remember that if both flags are present, --genesis wins — remove the unwanted one to avoid surprises

When it happens

Trigger: Invoking the command with neither `--faucet` nor `--genesis` resolved to a value — flags omitted, misspelled, or left None by a config file that was expected to provide them.

Common situations: New users following a tutorial that assumes a config file already carries a faucet URL; typos in flag names so clap leaves the fields None; automation that conditionally passes neither option on some branch.

Related errors

AI-assisted analysis of linera-io/linera-protocol@6c226ddcb3 (2026-08-22). Data as JSON: /api/errors/62d3ab3c5b165ebe. Report an issue: GitHub.