Bazel "Failed to query remote execution capabilities" in CI

On startup Bazel queries the remote endpoint for its capabilities before using it. When the endpoint is unreachable, misconfigured, or rejects the credentials, this handshake fails and the build stops before any action runs.

What this error means

A build fails early with "ERROR: Failed to query remote execution capabilities: UNAVAILABLE" or "UNAUTHENTICATED" for the configured --remote_cache or --remote_executor.

ERROR: Failed to query remote execution capabilities: UNAVAILABLE: io exception
Channel Pipeline: [...] Connection refused: remote.buildbuddy.io/...:443

Common causes

The remote endpoint URL or port is wrong

The --remote_cache/--remote_executor host is unreachable from CI, or uses the wrong scheme or port, so the capability check fails.

Missing or invalid credentials

The API key or credential helper was not injected in CI, so the endpoint returns UNAUTHENTICATED on the handshake.

How to fix it

Fix the endpoint and inject credentials

1. Confirm the remote URL, scheme (grpcs), and port are reachable from CI.
2. Inject the API key or header from a CI secret, not a committed value.
3. Re-run so the capability query succeeds.

build --remote_cache=grpcs://remote.example.com
build --remote_header=x-api-key=${REMOTE_KEY}

Degrade gracefully if remote is optional

Let the build continue on a local cache when the remote is temporarily unavailable instead of failing hard.

build --remote_local_fallback

How to prevent it

• Store remote cache credentials in CI secrets and inject at runtime.
• Use grpcs endpoints and confirm CI egress can reach them.
• Set --remote_local_fallback so a flaky remote does not block builds.

Related guides