[bug]: --yaml-dump-null-as-empty produces empty documents that kubectl rejects

[sergeykad]

Description of the bug

The --yaml-dump-null-as-empty flag (added in PR #861 to fix #843) does not fully resolve the null document issue. Instead of outputting --- null, it outputs an empty document (--- followed by ...) which kubectl still rejects:

error converting YAML to JSON: yaml: did not find expected node content

The flag changes the symptom but doesn't fix the underlying problem.

Steps to reproduce

1. Create a Helm chart with a comment before the first `---`:


# This is a comment
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: example


2. Compile with Kapitan using the flag:

kapitan compile -t my-target --yaml-dump-null-as-empty


3. Inspect the output - it contains:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: example
---
...


4. Apply with kubectl:

kubectl apply -f compiled/.../output.yaml


5. kubectl rejects with: `error converting YAML to JSON: yaml: did not find expected node content`

What happened?

Expected: --yaml-dump-null-as-empty should produce valid YAML that kubectl accepts.

Actual: The flag produces ---\n... (empty document) instead of --- null, but kubectl rejects both.

Suggested fix: Filter out null/empty documents entirely rather than changing their representation. When a Helm template produces a null document (from comments before ---), Kapitan should skip serializing that document altogether.

Additional context

• Affected charts: Any Helm chart with comments before the first --- (e.g., flink, kube-prometheus-stack)
• Current workaround: Post-processing with sed -i -e '/^---$/{ N; /^---\n\.\.\.$/d; }' file.yaml
• Related: [Helm] invalid Yaml document separator: null #843, PR Feature: Cli-flags for controlling the dumping behavior #861

Version (kapitan)

v0.31.0 (stable)

Version (Python)

I use kapitan directly (pip, docker)

Python virtual environment

• pyenv
• venv
• no environment

OS information

Ubuntu 22.04

Relevant log output

$ kubectl apply --dry-run=client -f flink-rbac.yaml
error converting YAML to JSON: yaml: did not find expected node content