grpcurl "server does not support the reflection API" in CI

By Daniel Zoghalchali·Latchkey

By default grpcurl discovers methods through gRPC server reflection. If the server never registered the reflection service, grpcurl cannot list or call methods by name and reports "server does not support the reflection API".

What this error means

grpcurl list or a call by method name fails with "Failed to list services: server does not support the reflection API", even though the server itself is reachable.

Failed to list services: server does not support the reflection API

Common causes

The reflection service is not registered

The server build did not enable gRPC reflection, so there is no reflection endpoint for grpcurl to query.

Reflection is intentionally off in production

Reflection is sometimes disabled outside development for security, leaving grpcurl without schema discovery.

How to fix it

Pass the proto files instead of using reflection

1. Point grpcurl at the .proto sources so it does not need reflection.
2. Include the import path and the file that defines the service.
3. Call the method by its fully-qualified name.

grpcurl -plaintext -import-path ./proto -proto users.proto \
  localhost:50051 users.v1.UserService/GetUser

Enable reflection on a CI/dev server

If you control the server and want discovery, register the reflection service for non-production builds.

import { ReflectionService } from '@grpc/reflection';
new ReflectionService(pkgDefinition).addToServer(server);

How to prevent it

• Pass -proto/-import-path to grpcurl when reflection is off.
• Enable reflection only on dev/CI servers if you rely on discovery.
• Keep proto sources available to CI smoke tests.

Frequently asked questions

Related guides

References

• GitHub Actions documentation