canopy-network/canopy · error · Exception

Unexpected handshake response

Error message

Unexpected handshake response

What it means

Thrown in PluginClient.handshake when the FSM's reply contains neither a config nor an error — an out-of-protocol response. It indicates a desynchronized or mismatched FSM (wrong message type, protocol drift, or corrupted transport) where the handshake cannot be interpreted.

Source

Thrown at plugin/kotlin/src/main/kotlin/com/canopy/plugin/PluginClient.kt:110

        logger.info { "Handshaking with FSM" }

        val configMsg = PluginToFSM.newBuilder()
            .setId(0)
            .setConfig(ContractConfig.toPluginConfig())
            .build()

        val response = sendSync(null, configMsg)

        when {
            response.hasConfig() -> {
                fsmConfig = response.config
                logger.info { "Handshake complete" }
            }
            response.hasError() -> {
                throw Exception("Handshake failed: ${response.error.msg}")
            }
            else -> {
                throw Exception("Unexpected handshake response")
            }
        }
    }

    /**
     * Read state from FSM
     */
    fun stateRead(contract: Contract, request: PluginStateReadRequest): PluginStateReadResponse {
        val msg = PluginToFSM.newBuilder()
            .setId(contract.fsmId)
            .setStateRead(request)
            .build()

        val response = sendSync(contract, msg)

        return when {
            response.hasStateRead() -> response.stateRead
            response.hasError() -> PluginStateReadResponse.newBuilder()

View on GitHub (pinned to ee8197d91d)

Solutions

1. Confirm plugin and FSM use the same proto message schema and protocol version.
2. Restart both plugin and FSM to re-establish a synchronized message sequence.
3. Inspect transport logging for dropped/garbled frames corrupting the response.

When it happens

Trigger: Thrown at plugin/kotlin/src/main/kotlin/com/canopy/plugin/PluginClient.kt:110 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

AI-assisted analysis of canopy-network/canopy@ee8197d91d (2026-09-06). Data as JSON: /api/errors/d8e4809cd04e0077. Report an issue: GitHub.