[Visual Test] Label preflight rejects duplicate label on run #30338232720, skipping Lavapipe screenshot capture

[MichaelFisher1997]

Workflow

https://github.com/OpenStaticFish/ZigCraft/actions/runs/30338232720

schedule event on dev at 2026-07-28T07:23:28Z (cron 43 4 * * *), head_sha=8d205ff (devenv migration #951).

Available evidence in the workspace

The only artifact left in the runner workspace after the job is:

• weston.log — the headless Wayland compositor started at 07:27:45.538 and was killed by caught signal 15 at 07:27:47.506 (≈2 s later). No game output, no Lavapipe, no Vulkan validation messages.
• No build-output.log (gitignored but expected to be uploaded by the Upload build log artifact step).
• No screenshot.png (the Check screenshot exists step only emitted screenshot_exists=false because no run produced it).

The absence of build-output.log and screenshot.png is the same shape as the previous day's failures (#950, #952, #954). Those runs are still open because the same root cause keeps re-firing on every schedule.

Failure output

The exact stderr/stdout of the game is not in the workspace, so the literal lines from this specific run cannot be quoted verbatim. However, the job summary confirms that the only failing step is Ensure visual-test label exists (step 8 in visual-test.yml), and that every step after it — Setup Lavapipe Vulkan, Run menu screenshot capture, Check screenshot exists (still ran, screenshot_exists=false), Compare against golden image, Upload screenshot artifact, Check build log exists (still ran, exists=false), Upload build log artifact, Run opencode visual verification — is either skipped or null. That exactly matches the documented behaviour of gh label create against an existing label on a 41-label repo:

label with name "run-visual-test" already exists; use `--force` to update its color and description
##[error]Process completed with exit code 1.

That message aborts the preflight; the run-with-log action never runs, so build-output.log is missing and screenshot.png is not produced. The Zig / Lavapipe / Vulkan / screenshot.zig code path is not exercised at all on this run, so neither the headless swapchain (modules/engine-graphics/src/vulkan_swapchain.zig:127-175), the screenshot capture (modules/engine-graphics/src/vulkan/screenshot.zig), nor the screenshot loop in src/game/app.zig:527-592 are involved.

Note that .github/prompts/visual-test-diagnose.md:7-9,42-43 still claims the workflow uses -Dscreenshot-path=screenshot.ppm — that is stale: .github/workflows/visual-test.yml:81 actually runs -Dscreenshot-path=screenshot.png -Dskip-present=true, and build.zig:1065 documents the option as "Capture a PNG screenshot after N frames and exit". The PPM hypothesis in the prompt is not what this run is doing; the Lavapipe / Vulkan / screenshot.zig path is not exercised at all.

Diagnosis

The visual-test workflow does not fail in the Vulkan / screenshot capture path. The Zig build and Lavapipe screenshot run never execute because the preflight gh label list / gh label create step exits non-zero, which causes every later step (including Run menu screenshot capture) to be skipped. build-output.log therefore does not exist in the workspace because the run-with-log action never ran.

Root cause is in .github/workflows/visual-test.yml:55-68 (Ensure visual-test label exists):

if ! gh label list --json name --jq '.[].name' | grep -q '^visual-test$'; then
  gh label create "visual-test" \
    --description "Issues from automated visual regression tests" \
    --color "E06C75"
fi
if ! gh label list --json name --jq '.[].name' | grep -q '^run-visual-test$'; then
  gh label create "run-visual-test" \
    --description "Run deterministic visual regression workflow on a PR" \
    --color "E06C75"
fi

gh label list paginates with a default page size of 30 and --jq '.[].name' only emits the first page. The repo currently has 41 labels (verified via gh label list --limit 100 --json name --jq '.[] | .name' → 41 names). On the unflagged 30-item call, run-visual-test (position 41) is not in page 1, so:

1. grep -q '^run-visual-test$' returns 1 (not found).
2. The if ! body runs gh label create "run-visual-test" ....
3. gh label create rejects the call with label with name "run-visual-test" already exists; use --force to update its color and description and exits 1.
4. The step's run: propagates exit 1 to the GitHub Actions runner, marking the step as failed (X).
5. All subsequent steps that rely on the default success() gating are skipped: Setup Lavapipe Vulkan, Run menu screenshot capture, Compare against golden image, Upload screenshot artifact, Upload build log artifact, Run opencode visual verification.
6. Only if: always() (Check screenshot exists, Check build log exists) and if: failure() || steps.screenshot.outcome == 'failure' || steps.check_screenshot.outputs.screenshot_exists != 'true' (Run opencode failure diagnosis) still execute, which is why this triage step is running at all.
7. weston.log survives because Stop headless Wayland compositor is also if: always(); it shows only the compositor startup that the parallel teardown step SIGTERMed.

This is the same failure that has been hitting the visual-test workflow every day since at least 2026-07-12 — see #916, #931, #935, #942, #944, #945, #946, #947, #949, #950, #952, #954. The most recent duplicates are #954 (run #30248571304) and #952 (run #30192579914), which document the identical root cause for the previous two schedule runs. Three consecutive days of open duplicates confirm the preflight logic is broken on every schedule run as soon as run-visual-test falls off page 1; the only thing that has kept the failure from firing more often is that some runs skip the preflight or gh happens to return the missing label by chance.

Origin of the failure

• File: .github/workflows/visual-test.yml
• Step: Ensure visual-test label exists (lines 55-68)
• Command: gh label list --json name --jq '.[].name' (default --limit 30; first page only)
• Condition: if ! ... | grep -q '^run-visual-test$'; then gh label create ...; fi — recreates an already-existing label once it falls off page 1
• Head commit on this run: 8d205ff ("build: migrate dev environment and CI from nix flake to devenv (build: migrate dev environment and CI from nix flake to devenv #951)"), so the Ensure visual-test label exists step is the unmodified block that shipped in the migration.

Suggested fix

Either fetch all pages when listing labels, or make gh label create failures non-fatal so a duplicate label never aborts the workflow:

if ! gh label list --json name --jq '.[].name' --paginate | grep -q '^visual-test$'; then
  gh label create "visual-test" \
    --description "Issues from automated visual regression tests" \
    --color "E06C75" || true
fi
if ! gh label list --json name --jq '.[].name' --paginate | grep -q '^run-visual-test$'; then
  gh label create "run-visual-test" \
    --description "Run deterministic visual regression workflow on a PR" \
    --color "E06C75" || true
fi

gh label create --force ... is the equivalent one-liner if you want the existing labels' colours / descriptions refreshed. Either change stops the failure from blocking Setup Lavapipe Vulkan and Run menu screenshot capture, which is the actual signal we need from this workflow.

Related

• [Visual Test] Label preflight skips Lavapipe screenshot capture on run #30248571304 #954 — run #30248571304 (2026-07-27), identical root cause
• [Visual Test] Label preflight rejects duplicate label on run #30192579914, skipping Lavapipe screenshot capture #952 — run #30192579914 (2026-07-26), identical root cause
• [Visual Test] Label preflight rejects duplicate label, skipping Lavapipe screenshot capture #950 — run #30148576016 (2026-07-25), identical root cause
• [Visual Test] PPM screenshot path is rejected before Vulkan readback #949 — run that prompted the stale "PPM rejected by detectScreenshotFormat" hypothesis; closed as duplicate of the preflight root cause
• [Visual Test] Workflow fails before game runs: 'Ensure visual-test label exists' step rejected by duplicate label #947 — run #30120170000 (2026-07-21), original "workflow fails before game runs" report

[github-actions]

Confirmed Bug. Reproduced locally with gh label list:

• Total labels: 41
• visual-test position: 21 (in default page 30 → first if passes)
• run-visual-test position: 41 (off page 30 → second if always falls through)

That matches the diagnosis exactly. gh label list --json name --jq '.[].name' paginates at 30 and only emits page 1, so the second if ! gh label list ... | grep -q '^run-visual-test$' always re-enters gh label create, which then exits 1 with "label with name "run-visual-test" already exists", failing the step and cascading skipped/null outcomes into every subsequent step. The Zig/Lavapipe/screenshot.zig code path is never entered, so headless swapchain and Vulkan code in modules/engine-graphics/src/vulkan_swapchain.zig and modules/engine-graphics/src/vulkan/screenshot.zig are not on the failure path at all.

Also confirmed the stale prompt claim:

• build.zig:1065 documents -Dscreenshot-path as "Capture a PNG screenshot after N frames and exit" (no PPM in the source).
• .github/workflows/visual-test.yml:81 runs -Dscreenshot-path=screenshot.png.
• .github/prompts/visual-test-diagnose.md:7-9,42-43 still references screenshot.ppm and PPM→PNG conversion — stale from before the PNG migration, and it is what kept the opencode diagnosis step filing the PPM hypothesis ([Visual Test] PPM screenshot path is rejected before Vulkan readback #949) instead of the real preflight root cause. Worth folding that into the same fix.

Scope: small and well-defined — do not split into sub-issues. One file, two if blocks (.github/workflows/visual-test.yml:55-68). Either of the two suggested patches works; I prefer the || true variant because it keeps the idempotent "create-if-missing" intent without depending on a label that already exists:

if ! gh label list --json name --jq '.[].name' --paginate | grep -q '^visual-test$'; then
  gh label create "visual-test" --description "Issues from automated visual regression tests" --color "E06C75" || true
fi
if ! gh label list --json name --jq '.[].name' --paginate | grep -q '^run-visual-test$'; then
  gh label create "run-visual-test" --description "Run deterministic visual regression workflow on a PR" --color "E06C75" || true
fi

--paginate is the more correct fix long-term (it avoids the silent fallback that hid the bug for months), but || true alone is the minimal change that unblocks the schedule.

Suggested follow-ups once the workflow patch lands:

1. Update .github/prompts/visual-test-diagnose.md lines 7-9 and 42-43 to reference PNG and the actual -Dscreenshot-path=screenshot.png flag (or link to build.zig:1065).
2. Close [Visual Test] Label preflight skips Lavapipe screenshot capture on run #30248571304 #954, [Visual Test] Label preflight rejects duplicate label on run #30192579914, skipping Lavapipe screenshot capture #952, [Visual Test] Label preflight rejects duplicate label, skipping Lavapipe screenshot capture #950, [Visual Test] PPM screenshot path is rejected before Vulkan readback #949, [Visual Test] Workflow fails before game runs: 'Ensure visual-test label exists' step rejected by duplicate label #947, [Visual Test] Label preflight aborts before screenshot capture #945, [Visual Test] Label bootstrap failure prevents menu screenshot run #944, [Visual Test] Label preflight prevents screenshot capture on run #26 #942, [Visual Test] Label preflight regressed again: unpaginated gh label list still misses run-visual-test on run #20 #935, [Visual Test] Label preflight regressed: gh label list pagination skips run-visual-test on run #19 #931, [Visual Test] Label preflight fails: gh label list only returns first 30 labels, run-visual-test is on page 2 #916 as duplicates of this report once the workflow turn is green; the daily-issue churn from this single bug is masking any real visual regression signal.

No reproduction steps or crash logs are needed from the reporter — the failure mode is fully characterised by the workflow YAML and the label count.

[github-actions]

Comment posted on issue #956: #956 (comment)

Validated the analysis against the repo: confirmed 41 labels with run-visual-test at position 41 (off the default 30-page), build.zig:1065 documents the option as PNG, and .github/prompts/visual-test-diagnose.md:7-9,42-43 is stale (still says PPM). Classified as a Bug, scope is small (single workflow file, two if blocks at lines 55-68 — should not be split), and recommended a minimal || true patch plus --paginate as the more correct long-term fix, with cleanup of the stale prompt and closing the duplicate issues (#916, #931, #935, #942, #944-947, #949-950, #952, #954) once the workflow turns green.

opencode session  |  github run