linera-io/linera-protocol · error · anyhow

TLS not supported between proxy and shards.

Error message

TLS not supported between proxy and shards.

What it means

Raised in `ServerContext::run` (linera-service server.rs) when the validator server's internal network is configured as `NetworkProtocol::Grpc(TlsConfig::Tls)`. The gRPC shards spawned by the server only support cleartext connections; TLS in a Linera deployment is terminated at the proxy's public side, never between proxy and shards. The server aborts at startup instead of running a half-supported TLS listener.

Source

Thrown at linera-service/src/server.rs:359

            }
        };

        let mut join_set = match self.server_config.internal_network.protocol {
            NetworkProtocol::Simple(protocol) => self.spawn_simple(
                &listen_address,
                states,
                protocol,
                &shutdown_notifier,
                enable_memory_profiling,
            ),
            NetworkProtocol::Grpc(tls_config) => match tls_config {
                TlsConfig::ClearText => self.spawn_grpc(
                    &listen_address,
                    states,
                    &shutdown_notifier,
                    enable_memory_profiling,
                ),
                TlsConfig::Tls => bail!("TLS not supported between proxy and shards."),
            },
        };

        join_set.await_all_tasks().await;

        Ok(())
    }
}

#[derive(clap::Parser)]
#[command(
    name = "linera-server",
    about = "Server implementation (aka validator shard) for the Linera blockchain",
    version = linera_version::VersionInfo::default_clap_str(),
)]
struct ServerOptions {
    /// Subcommands. Acceptable values are run and generate.
    #[command(subcommand)]

View on GitHub (pinned to 6c226ddcb3)

Solutions

1. Set `internal_network.protocol` to `grpc` with `tls = "cleartext"` in the server config
2. Keep TLS only on the validator's external/public protocol (terminated at the proxy)
3. Regenerate the config with the current linera-configgen to get valid defaults
4. Check the proxy config too — the proxy must connect to shards over cleartext gRPC

Example fix

# before (config.toml)
[internal_network]
protocol = { type = "grpc", tls = "tls" }

# after
[internal_network]
protocol = { type = "grpc", tls = "cleartext" }

// Rust: reject TLS internal configs before starting the server
match &server_config.internal_network.protocol {
    NetworkProtocol::Grpc(TlsConfig::Tls) => {
        return Err(anyhow::anyhow!(
            "internal network must be grpc cleartext; TLS terminates at the proxy"
        ));
    }
    _ => {}
}

When it happens

Trigger: Running `linera server` with `server_config.internal_network.protocol = Grpc(Tls)`; reusing a public/external TLS setting for the internal network section in config.toml.

Common situations: Hardening a deployment and mistakenly enabling TLS on the internal network; hand-editing config.toml and copying the external `grpc tls` block into `internal_network`; following generic gRPC TLS guidance that does not apply to proxy-to-shard links.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• network protocol mismatch: cannot have {internal_protocol} a
• Expecting format `(tcp|udp|grpc|grpcs):host:port`
• {s}
• Validator spec must be in format: public_key,account_key,add
• MissingCertificates

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