nautechsystems/nautilus_trader · error

Deployment manifest is missing a required role

Error message

Deployment manifest is missing a required role

What it means

The validator collects the set of BlockchainContractRole values declared across manifest.contracts and requires that every role needed by the adapter's routing flow is present: Router, Factory, WrappedNative, Quote, Token, and Pool. This error means at least one of these required roles has no contract entry in the deployment manifest, so the verifier cannot pin the full on-chain contract topology.

Solutions

  1. Add contract entries covering all six required roles (Router, Factory, WrappedNative, Quote, Token, Pool) with valid addresses and runtime code hashes
  2. Deploy/register the missing contracts, then regenerate the manifest
  3. Check for role enum renames between manifest versions and update the generator

Example fix

// before
"contracts": [{"role": "router", ...}, {"role": "factory", ...}]
// after
"contracts": [{"role": "router", ...}, {"role": "factory", ...}, {"role": "wrapped_native", ...}, {"role": "quote", ...}, {"role": "token", ...}, {"role": "pool", ...}]
Defensive patterns

Strategy: validation

Validate before calling

const REQUIRED: [Role; 6] = [Role::Router, Role::Factory, Role::WrappedNative, Role::Quote, Role::Token, Role::Pool];
let roles: HashSet<Role> = manifest.contracts.iter().map(|c| c.role).collect();
assert!(REQUIRED.iter().all(|r| roles.contains(r)), "manifest missing a required role");

Try / catch

match validate_manifest(&config) {
    Err(e) if e.to_string().contains("missing a required role") => {
        eprintln!("add contract entries for all required roles: {e}");
    }
    Err(e) => return Err(e),
    Ok(v) => v,
}

Prevention

When it happens

Trigger: Running manifest verification on a manifest whose contracts[] omit any contract with role Router, Factory, WrappedNative, Quote, Token, or Pool — e.g. generating a minimal manifest with only the implementation contract, or dropping a role during a hand edit.

Common situations: New chain onboarding where only some contracts were deployed/registered yet; a manifest template that predates a newly required role; script filtering contracts by allowlist and dropping one; renames of role enum values between manifest versions.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors


AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/fef4ec3c869c19ff. Report an issue: GitHub.

Appendix: source

Thrown at crates/adapters/blockchain/src/rpc/verification.rs:1347

            })?;
        anyhow::ensure!(
            target_contract.role == BlockchainContractRole::Implementation
                && target_contract
                    .runtime_code_hash
                    .eq_ignore_ascii_case(&proxy.target_code_hash),
            "Proxy target role or code hash conflicts with its deployment identity"
        );
    }

    for required in [
        BlockchainContractRole::Router,
        BlockchainContractRole::Factory,
        BlockchainContractRole::WrappedNative,
        BlockchainContractRole::Quote,
        BlockchainContractRole::Token,
        BlockchainContractRole::Pool,
    ] {
        anyhow::ensure!(
            roles.contains(&required),
            "Deployment manifest is missing a required role"
        );
    }

    for token in &manifest.tokens {
        let address = Address::from_str(&token.address)
            .map_err(|_| anyhow::anyhow!("Token manifest address is invalid"))?;
        anyhow::ensure!(
            contract_addresses.contains(&address),
            "Token manifest address has no contract identity"
        );
        anyhow::ensure!(
            !token.name.trim().is_empty()
                && !token.symbol.trim().is_empty()
                && matches!(token.asset_role.as_str(), "base" | "quote" | "both"),
            "Token manifest identity or asset role is invalid"
        );

View on GitHub (pinned to 18893faf8b)