apache/beam · error · CoderException

cannot encode a null value

Error message

cannot encode a null value

What it means

FileResult.Coder.encode() throws CoderException when asked to encode a null FileResult value. Beam coders must reject nulls explicitly, so a null reaching the coder indicates an upstream bug or missing element filtering.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileBasedSink.java:1204

    public static <DestinationT> FileResultCoder<DestinationT> of(
        Coder<BoundedWindow> windowCoder, Coder<DestinationT> destinationCoder) {
      return new FileResultCoder<>(windowCoder, destinationCoder);
    }

    @Override
    public List<? extends Coder<?>> getCoderArguments() {
      return Collections.singletonList(destinationCoder);
    }

    @Override
    public List<? extends Coder<?>> getComponents() {
      return Arrays.asList(windowCoder, destinationCoder);
    }

    @Override
    public void encode(FileResult<DestinationT> value, OutputStream outStream) throws IOException {
      if (value == null) {
        throw new CoderException("cannot encode a null value");
      }
      FILENAME_CODER.encode(value.getTempFilename().toString(), outStream);
      windowCoder.encode(value.getWindow(), outStream);
      PANE_INFO_CODER.encode(value.getPaneInfo(), outStream);
      SHARD_CODER.encode(value.getShard(), outStream);
      destinationCoder.encode(value.getDestination(), outStream);
    }

    @Override
    public FileResult<DestinationT> decode(InputStream inStream) throws IOException {
      String tempFilename = FILENAME_CODER.decode(inStream);
      BoundedWindow window = windowCoder.decode(inStream);
      PaneInfo paneInfo = PANE_INFO_CODER.decode(inStream);
      int shard = SHARD_CODER.decode(inStream);
      DestinationT destination = destinationCoder.decode(inStream);
      return new FileResult<>(
          FileSystems.matchNewResource(tempFilename, false /* isDirectory */),
          shard,

View on GitHub (pinned to 12126d8942)

Solutions

1. Find and fix the upstream step emitting null FileResult values (filter with null checks before coding).
2. Ensure sink Writer operations never return null results.
3. If nulls are expected, filter them: filter(Objects::nonNull) before the coding step.

Example fix

// before
results.add(null);
// after
if (result != null) { results.add(result); }

boolean isNonNullFileResult(FileResult<?> r) { return r != null; }

try { coder.encode(value, out); } catch (CoderException e) { throw new IllegalStateException("Null or malformed FileResult reached coder — check upstream DoFns", e); }

When it happens

Trigger: A null FileResult element entering a codable step (e.g. WriteFiles/DynamicDestinations result PCollections), typically from user DoFns emitting null or buggy group/key extraction.

Common situations: Custom pipelines that build FileResult lists manually, or joins/coGroup producing null outputs passed onward to write steps.

Related errors

• cannot encode a null Integer
• cannot encode a null Long
• cannot encode a null Short
• cannot encode a null BitSet
• cannot encode a null byte[]

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