Go client error codes

This page maps Control RPC conditions to errors in vsctl.

The Go client exposes a three-level error model: base interface (vsctl.Error), derived category interfaces (for example vsctl.ConnectionError), and sentinel values (for example vsctl.ErrEngineUnavailable).

• error
  • vsctl.Error
    • vsctl.ConfigurationError
      • vsctl.ErrClientConfigInvalid
    • vsctl.ConnectionError
      • vsctl.ErrEngineNotDiscovered
      • vsctl.ErrEngineUnavailable
    • vsctl.CompatibilityError
      • vsctl.ErrEngineVersionMismatch
      • vsctl.ErrEngineUnexpectedResponse
    • vsctl.RuntimeError
      • vsctl.ErrEngineFault
    • vsctl.RequestError
      • vsctl.ErrRequestInvalid
      • vsctl.ErrResourceNotFound
      • vsctl.ErrResourceAlreadyExists
      • vsctl.ErrResourceExhausted
      • vsctl.ErrPermissionDenied
    • vsctl.LifecycleError
      • vsctl.ErrClientClosed
      • vsctl.ErrRequestTimeout
      • vsctl.ErrRequestCanceled

Use errors.As when you want interface-level matching (vsctl.Error for any client error, or a category interface such as vsctl.ConnectionError). Use errors.Is when you want to match a specific sentinel value such as vsctl.ErrEngineUnavailable.

The library uses errors.Join to keep both classification and cause details. Request paths join the vsctl sentinel with the underlying gRPC/context/I/O error, and Close() may join multiple cleanup failures. This lets callers match either level with errors.As / errors.Is.

var sdkErr vsctl.Error
if errors.As(err, &sdkErr) {
    // handle any vsctl error
}

var connErr vsctl.ConnectionError
if errors.As(err, &connErr) {
    // handle connection category
}

if errors.Is(err, vsctl.ErrEngineUnavailable) {
    // handle a specific condition
}

Go interface	Interface description	Go error code	Code description	gRPC status codes
ConfigurationError	Invalid or incomplete client configuration detected locally before any request is sent to engine.	ErrClientConfigInvalid	Invalid or incomplete client configuration.	none (client-side condition)
ConnectionError	Engine cannot be reached: no engine discovered, connection not established, or existing connection/session lost.	ErrEngineNotDiscovered	Engine not discovered during client initialization.	none (client-side condition)
		ErrEngineUnavailable	Engine unavailable: connect failed, connection/session lost, engine stopped/restarted.	UNAVAILABLE
CompatibilityError	Client and engine versions/protocol are not compatible.	ErrEngineVersionMismatch	Engine version is incompatible with the client.	UNIMPLEMENTED
		ErrEngineUnexpectedResponse	Successful response is semantically invalid or incomplete.	none (client-side condition)
RuntimeError	Engine failed while handling request (not rejecting it).	ErrEngineFault	Temporary engine failure, or unmapped engine status.	ABORTED, INTERNAL, any unmapped engine status
RequestError	Request reached engine and was rejected by it.	ErrRequestInvalid	Request is ill-formed or has invalid arguments.	INVALID_ARGUMENT
		ErrResourceNotFound	Requested identifier was not found.	NOT_FOUND
		ErrResourceAlreadyExists	Requested identifier already exists.	ALREADY_EXISTS
		ErrResourceExhausted	Operation rejected because a resource limit was reached.	RESOURCE_EXHAUSTED
		ErrPermissionDenied	Operation rejected due to insufficient permissions.	PERMISSION_DENIED
LifecycleError	Request terminated locally before engine response.	ErrClientClosed	Operation interrupted because the client was closed.	none (client-side condition)
		ErrRequestTimeout	Request aborted by a client-side timeout.	DEADLINE_EXCEEDED (client-side condition)
		ErrRequestCanceled	Request canceled via caller context.	CANCELLED (client-side condition)