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.

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)

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", ...}]

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");

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,
}

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

• Allowed token pair {token_in} -> {token_out} is not fully pi
• Quote spend limit decimals do not match the deployment manif
• Chart function must be callable, was {type(f)}
• Chart function must be callable, was {type(func)}
• Chart '{name}' not found.{suggestion_text} Available charts:

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