canopy-network/canopy · error · Exception

Handshake failed: ${response.error.msg}

Error message

Handshake failed: ${response.error.msg}

What it means

Thrown in PluginClient.handshake when the FSM's reply to the config handshake message carries an error field; the FSM-side error message is embedded. It means the FSM rejected the plugin's contract configuration at startup, so the plugin cannot proceed to normal operation.

Source

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

     * Perform handshake with FSM
     */
    private fun handshake() {
        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)

View on GitHub (pinned to ee8197d91d)

Solutions

1. Read the embedded FSM error message to see why the config was rejected and align ContractConfig with FSM expectations.
2. Verify the FSM is running a compatible protocol version before restarting.
3. Retry the handshake after fixing the config; the exception propagates from start(), so the plugin restarts.

When it happens

Trigger: Thrown at plugin/kotlin/src/main/kotlin/com/canopy/plugin/PluginClient.kt:107 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/74fc3dd3628e8c5e. Report an issue: GitHub.