Kong · shivaygupta-dotcom · Jun 5, 2026 · Jun 4, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/lint/lint.go b/lint/lint.go
@@ -2,11 +2,14 @@ package lint
 
 import (
 	"fmt"
+	"os"
 	"strings"
 
 	"github.com/daveshanley/vacuum/motor"
 	"github.com/daveshanley/vacuum/rulesets"
 	"github.com/kong/go-apiops/filebasics"
+	"github.com/kong/go-database-reconciler/pkg/cprint"
+	"sigs.k8s.io/yaml"
 )
 
 const plainTextFormat = "plain"
@@ -81,6 +84,17 @@ func WithContent(
 	if err != nil {
 		return nil, err
 	}
+	var parsedContent interface{}
+	if err := yaml.Unmarshal(stateFileBytes, &parsedContent); err == nil && parsedContent == nil {
+		// Return empty results with a warning instead of an error
+		// to maintain backward compatibility with older deck versions
+		cprint.UpdatePrintlnStdErr(os.Stderr, "Warning: state file is empty or contains only comments, skipping linting")
+		return map[string]interface{}{
+			"total_count": 0,
+			"fail_count":  0,
+			"results":     []Result{},
+		}, nil
+	}
 	ruleSetResults := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
 		RuleSet:           customRuleSet,
 		Spec:              stateFileBytes,

diff --git a/tests/integration/lint_test.go b/tests/integration/lint_test.go
@@ -165,3 +165,55 @@ func Test_LintStructured(t *testing.T) {
 		})
 	}
 }
+
+func Test_LintEmptyOrCommentsOnly(t *testing.T) {
+	tests := []struct {
+		name        string
+		stateFile   string
+		rulesetFile string
+	}{
+		{
+			name:        "comments only file",
+			stateFile:   "testdata/lint/001-simple-lint/comments-only.yaml",
+			rulesetFile: "testdata/lint/001-simple-lint/ruleset.yaml",
+		},
+		{
+			name:        "empty file",
+			stateFile:   "testdata/lint/001-simple-lint/empty.yaml",
+			rulesetFile: "testdata/lint/001-simple-lint/ruleset.yaml",
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			stdout, stderr, err := fileLintWithStderr(
+				"-s", tc.stateFile,
+				tc.rulesetFile,
+			)
+			require.NoError(t, err)
+			assert.Contains(t, stderr, "Warning: state file is empty or contains only comments, skipping linting")
+			assert.Empty(t, stdout)
+		})
+
+		t.Run(tc.name+" json output", func(t *testing.T) {
+			stdout, stderr, err := fileLintWithStderr(
+				"-s", tc.stateFile,
+				"--format", "json",
+				tc.rulesetFile,
+			)
+			require.NoError(t, err)
+
+			// Verify warning message appears in stderr (not stdout)
+			assert.Contains(t, stderr, "Warning: state file is empty or contains only comments, skipping linting")
+
+			// Verify JSON output is valid and contains expected structure
+			var output lintErrors
+			err = json.Unmarshal([]byte(stdout), &output)
+			require.NoError(t, err, "JSON output should be valid")
+
+			// Verify empty results
+			assert.Equal(t, 0, output.TotalCount)
+			assert.Equal(t, 0, output.FailCount)
+			assert.Empty(t, output.Results)
+		})
+	}
+}
diff --git a/tests/integration/test_utils.go b/tests/integration/test_utils.go
@@ -468,6 +468,36 @@ func fileLint(opts ...string) (string, error) {
 	return stripansi.Strip(string(out)), cmdErr
 }
 
+func fileLintWithStderr(opts ...string) (stdout string, stderr string, err error) {
+	deckCmd := cmd.NewRootCmd()
+	args := []string{"file", "lint"}
+	if len(opts) > 0 {
+		args = append(args, opts...)
+	}
+	deckCmd.SetArgs(args)
+
+	// capture stdout
+	rescueStdout := os.Stdout
+	rOut, wOut, _ := os.Pipe()
+	os.Stdout = wOut
+
+	// capture stderr
+	rescueStderr := os.Stderr
+	rErr, wErr, _ := os.Pipe()
+	os.Stderr = wErr
+
+	cmdErr := deckCmd.ExecuteContext(context.Background())
+
+	wOut.Close()
+	wErr.Close()
+	outBytes, _ := io.ReadAll(rOut)
+	errBytes, _ := io.ReadAll(rErr)
+	os.Stdout = rescueStdout
+	os.Stderr = rescueStderr
+
+	return stripansi.Strip(string(outBytes)), stripansi.Strip(string(errBytes)), cmdErr
+}
+
 func fileConvert(opts ...string) (string, error) {
 	deckCmd := cmd.NewRootCmd()
 	args := []string{"file", "convert"}

diff --git a/tests/integration/testdata/lint/001-simple-lint/comments-only.yaml b/tests/integration/testdata/lint/001-simple-lint/comments-only.yaml
@@ -0,0 +1,4 @@
+# This is a commented YAML file
+# _format_version: "3.0"
+# services:
+#   - name: my-service
diff --git a/tests/integration/testdata/lint/001-simple-lint/empty.yaml b/tests/integration/testdata/lint/001-simple-lint/empty.yaml
@@ -0,0 +1 @@
+