YAML Debugging Workflow

When kubectl, Actions, or Compose rejects a file, use a repeatable workflow instead of random edits.

Step 1: Capture the exact file bytes

Copy the failing file from git—not a screenshot, not a Slack snippet with smart quotes changed. Hidden characters cause false fixes.

Step 2: Validate without mutating

Run validate-only mode first. You want parser feedback on the current text, not an auto-formatted variant that hides the original mistake.

Step 3: Jump to line and column

Parser messages such as "line 18, column 3" map to a specific indent or token. Fix that spot before reformatting the entire file.

Step 4: Format and review diff

After syntax is valid, format with your team's indent standard. Read the diff—formatting should not change meaning, only whitespace and optionally key order.

Step 5: JSON round-trip when stuck

If YAML is generated from JSON tooling, convert YAML → JSON → YAML to expose structural surprises. If JSON looks wrong, fix the data model before debating indentation.

Step 6: Re-run the original tool

Apply with kubectl dry-run, re-run the workflow, or docker compose config—domain validators catch issues parsers cannot see (unknown fields, wrong API versions).

Security reminder

Never paste production secrets into shared formatter links. Use redacted samples when collaborating.