canopy-network/canopy · error

plugin RPC server disabled (failed to start on $addr)

Error message

plugin RPC server disabled (failed to start on $addr)

What it means

Logged (not thrown fatally) in Rpc.start when the plugin's optional custom RPC server fails to bind its address — typically an invalid addr string or a port already in use. By design this failure does NOT crash the plugin; the server is simply disabled and the rest of the plugin keeps running.

Source

Thrown at plugin/kotlin/src/main/kotlin/com/canopy/plugin/Rpc.kt:78

        // The custom RPC server is OPTIONAL. Parsing the address or binding the port (e.g. already
        // in use) can throw; a failure here must NOT crash the plugin — log it and continue without
        // an RPC server so plugins that don't use this feature are unaffected.
        try {
            // parse host:port (default host 0.0.0.0 binds all interfaces)
            val lastColon = addr.lastIndexOf(':')
            val host = if (lastColon > 0) addr.substring(0, lastColon) else "0.0.0.0"
            val port = if (lastColon >= 0) addr.substring(lastColon + 1).toInt() else addr.toInt()

            val server = HttpServer.create(InetSocketAddress(host, port), 0)
            // no routes are registered by default; builders add their own here (see TUTORIAL.md)
            server.executor = null

            // log the build marker so the running version is obvious in the log
            logger.info { "plugin RPC server ($PLUGIN_BUILD) listening on $addr (no custom routes registered)" }
            server.start()
        } catch (e: Exception) {
            logger.warn(e) { "plugin RPC server disabled (failed to start on $addr)" }
        }
    }
}

View on GitHub (pinned to ee8197d91d)

Solutions

1. Check the log for the underlying bind exception (port in use, invalid host:port).
2. Free the port or change rpc_address in the plugin config, then restart the plugin.
3. If RPC is not needed, ignore the warning — the plugin functions without the custom RPC server.

When it happens

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

Common situations: See trigger scenarios.

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