unionlabs/union · error

config file must be specified

Error message

config file must be specified

What it means

voyager's CLI dispatch get_voyager_config received None for the config file path and immediately errors with 'config file must be specified'. Almost every voyager subcommand (run, plugin, msg, queue, …) resolves its configuration through this function, so running voyager without pointing it at a config file fails here before anything else happens. The path is a plain Option<OsString> argument (the VOYAGER_CONFIG_FILE_PATH env fallback is commented out in cli.rs), so it must be supplied explicitly.

Source

Thrown at voyager/src/cli.rs:78

                        config_file_path.to_string_lossy()
                    )
                })
                .and_then(|s| match ext.map(OsStr::as_encoded_bytes) {
                    Some(b"jsonc") => serde_jsonc::from_str::<Config>(&s).with_context(|| {
                        format!(
                            "unable to parse the config file at `{}`",
                            config_file_path.to_string_lossy()
                        )
                    }),
                    _ => serde_json::from_str::<Config>(&s).with_context(|| {
                        format!(
                            "unable to parse the config file at `{}`",
                            config_file_path.to_string_lossy()
                        )
                    }),
                })
        }
        None => Err(anyhow!("config file must be specified")),
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Default, clap::ValueEnum, derive_more::Display)]
pub enum LogFormat {
    #[default]
    #[display("text")]
    Text,
    #[display("json")]
    Json,
}

#[derive(Debug, Subcommand)]
#[allow(clippy::large_enum_variant)]
pub enum Command {
    /// Config related subcommands.
    #[command(subcommand)]
    Config(ConfigCmd),

View on GitHub (pinned to 031785bb6d)

Solutions

  1. Pass the config file explicitly: voyager --config /path/to/voyager-config.json <subcommand> (check the exact flag with voyager --help).
  2. If you want an env-var default, uncomment/implement the env = "VOYAGER_CONFIG_FILE_PATH" support in cli.rs rather than relying on it.
  3. Generate a starting config with the schema/config default commands (e.g. the config default / config schema subcommands) if you don't have one yet.
  4. Wrap repeated invocations in a script that always exports and injects the config path.

Example fix

# before
voyager plugin info client-eth

# after
voyager --config ./voyager-config.json plugin info client-eth
Defensive patterns

Strategy: validation

Validate before calling

// Rust caller-side guard before shelling out
let cfg = std::path::Path::new(config_path);
anyhow::ensure!(cfg.is_file(), "missing config file: {}", cfg.display());
let cmd = format!("voyager --config {} {subcommand}", cfg.display());

Type guard

fn has_config_arg(argv: &[OsString]) -> bool {
    argv.iter().skip(1).any(|a| a == "--config" || a.to_string_lossy().starts_with("--config="))
}

Try / catch

let config = get_voyager_config(app.config_file_path.as_deref())
    .context("voyager needs --config; run `voyager --help` for usage")?;

Prevention

When it happens

Trigger: Invoking any config-dependent subcommand without the --config flag, e.g. 'voyager plugin info <name>' or 'voyager run' with no positional/config argument; scripts that assumed an env-var default (currently disabled); shell aliases dropping the flag.

Common situations: Following docs that omitted --config; upgrading from a version where a config default or env var existed; copy-pasting a command template that used a different flag name.

Related errors

AI-assisted analysis of unionlabs/union@031785bb6d (2026-08-16). Data as JSON: /api/errors/7ebfa1a3c1ae0c55. Report an issue: GitHub.