Troubleshooting

Common symptoms and how to resolve them. For the underlying model, see Error handling.

Installation

pip install / npm install can't find the package. The SDK is served from the Buf Schema Registry, not the default registries. Make sure you pointed your package manager at the BSR — the --extra-index-url for pip, or the @buf registry line in .npmrc for npm. See Install.

buf generate fails for C++. Confirm the buf CLI is installed and your buf.gen.yaml matches the example in Install. Generation pulls plugins remotely, so it needs network access to the BSR — for air-gapped builds, vendor the generated code (see Robust streaming).

Authentication and connection

Calls fail with UNAUTHENTICATED. The token is missing, expired, or invalid. Check PLATFORM_TOKEN is set and current, and that it is attached to the channel as call credentials. See Authenticate.

TLS / certificate verification errors. The endpoint is likely on a private network with a self-signed certificate. Supply the vessel's CA certificate to the channel — see Connecting to a vessel.

Calls fail with UNAVAILABLE. The endpoint is unreachable: check the host:port, network reachability to the vessel, and that the deployment is up. This is transient — retry with backoff.

Calls fail with NOT_FOUND. The vessel_id isn't served by this endpoint. Confirm the IDs your endpoint serves through your engagement — see Connecting to a vessel.

Calls and streams

A command returned without error, but the vessel didn't act. A command RPC returning is only delivery. Check the success/message on the response, and watch the matching state stream to confirm the effect. See Error handling.

A stream stops emitting after a while. Links drop. Wrap streams in the reconnect-with-backoff pattern so they re-open automatically and re-converge on the current value — see Streaming and reconnection.

An optional field reads as a default/zero value. Fields that may be unavailable are declared optional. Check presence (msg.HasField("range") in Python) before reading them, rather than trusting a 0.

Still stuck?

Reach out through your Greenroom engagement channel with the failing call, the gRPC status code or message, and the schema version you've pinned.