apache/beam · error · IllegalStateException

Unknown type

Error message

Unknown type 

What it means

ManagedChannelFactory.forDescriptor switches over the ApiServiceDescriptor's enum method type to build a gRPC channel. Hitting the default branch means the descriptor carried an enum value this Beam version does not recognize, so channel creation cannot proceed and an IllegalStateException is thrown.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/fn/channel/ManagedChannelFactory.java:83

        channelBuilder =
            NettyChannelBuilder.forAddress(address)
                .channelType(
                    address instanceof DomainSocketAddress
                        ? EpollDomainSocketChannel.class
                        : EpollSocketChannel.class)
                .eventLoopGroup(new EpollEventLoopGroup());
        break;

      case DEFAULT:
        channelBuilder = ManagedChannelBuilder.forTarget(apiServiceDescriptor.getUrl());
        break;

      case IN_PROCESS:
        channelBuilder = InProcessChannelBuilder.forName(apiServiceDescriptor.getUrl());
        break;

      default:
        throw new IllegalStateException("Unknown type " + type);
    }

    channelBuilder =
        channelBuilder
            .usePlaintext()
            // Set the message size to max value here. The actual size is governed by the
            // buffer size in the layers above.
            .maxInboundMessageSize(Integer.MAX_VALUE)
            // Disable automatic retries as it introduces complexity and we send long-lived
            // rpcs which will exceed the per-rpc retry request buffer and not be retried
            // anyway. See
            // https://github.com/grpc/proposal/blob/master/A6-client-retries.md#when-retries-are-valid
            .disableRetry()
            .intercept(interceptors);
    if (directExecutor) {
      channelBuilder = channelBuilder.directExecutor();
    }
    return channelBuilder.build();

View on GitHub (pinned to 12126d8942)

Solutions

1. Align Beam versions between the runner/job server and SDK harness so channel type enums match.
2. Check the ApiServiceDescriptor.getUrl() and its type field for accidental custom/incorrect values.
3. Upgrade the SDK containing ManagedChannelFactory to a version supporting the descriptor's channel type.

Example fix

// before
ApiServiceDescriptor descriptor = ApiServiceDescriptor.newBuilder()
    .setUrl("localhost:0")
    .setChannelType("unsupported_future_type") // unknown enum
    .build();
// after
ApiServiceDescriptor descriptor = ApiServiceDescriptor.newBuilder()
    .setUrl("localhost:0") // rely on default/known channel type
    .build();

if (!EnumSet.allOf(ManagedChannelFactory.ChannelType.class)
    .contains(descriptor.getChannelType()))
  throw new IllegalArgumentException("unsupported channel type: " + descriptor.getChannelType());

try { channel = ManagedChannelFactory.forDescriptor(desc); } catch (IllegalStateException e) { /* version skew: align Beam versions */ throw e; }

When it happens

Trigger: An ApiServiceDescriptor from a newer/older Beam or runner specifies a channel type enum absent from this client's ManagedChannelFactory.ChannelType (only LEGACY/remote and IN_PROCESS are handled).

Common situations: Version skew between the job server/expansion service and the SDK harness; custom descriptors built with the wrong enum; mixing Beam versions in container images.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown ValueKind number: {}
• State stream is closed.
• Unrecognized value for stable unique names:
• Instruction id was registered twice
• Cannot convert unknown %s to %s: %s

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/6d44c4c7f001d3c7. Report an issue: GitHub.