3 tutorials 404 on PROD — never published due to stepCount=0 (upstream step-heading format defects)

Summary (corrected)

Correction: My original framing — "false positive, probe hits legacy AEM pre-cutover" — was wrong. Cutover is complete; developers.sap.com is fronted by our PROD approuter and there is no AEM site. Verified: developers.sap.com and the PROD approuter return identical status codes for every slug below.

The health check is correct. These four tutorials are status=ACTIVE in the PROD catalog but have no published content BLOB in PROD (ContentCurrent has no row for them), so PROD serves a genuine HTTP 404 → correctly flagged BROKEN. They render fine on DEV (200), which is the tell: this is a DEV→PROD content-publish gap, not a check defect and not a legacy-site artifact.

Affected tutorials

slug	PROD catalog	PROD ContentCurrent	developers.sap.com (=PROD)	DEV approuter
s4hc-abap-environment-create-custom-api	ACTIVE	absent	404	200
btp-transport-management-cpi-01-use-case	ACTIVE	absent	404	200
private-link-gcp	ACTIVE	absent	404	200
abap-environment-create-tile	ACTIVE	absent	404	200

abap-connectivity-daemon-simple (originally SLOW) is published and live everywhere — ContentCurrent present (165 KB, published 2026-10-15), 200 on PROD and DEV. Its SLOW was a transient latency blip, not a defect. Dropped from this issue.

Root cause

PROD Tutorials rows are ACTIVE (so the catalog/sitemap/health-check all expect them served) but no content was ever published to PROD's HANA ContentCurrent. PROD serves tutorial HTML strictly from HANA BLOBs with no static fallback, so an ACTIVE row without a ContentCurrent BLOB = 404. The same slugs have local Hugo source and serve on DEV, confirming the content exists and simply has not been published through to PROD.

Suggested fix

Publish the four tutorials to PROD:

gh workflow run rebuild-content.yml --repo sap-tutorials/tutorials-ims --ref main \
  -f slug=s4hc-abap-environment-create-custom-api

(repeat per slug, or a single multi-slug / mode=full run)

Then re-run the URL health check and confirm linkStatus clears to OK. If any slug is intentionally retired, set its PROD catalog row inactive instead so it drops out of the catalog and the check (same remediation as #2834).

Verification

developers.sap.com/tutorials/<slug>/ and PROD approuter .../tutorials/<slug>/: identical 404 for all four; identical 200 for abap-connectivity-daemon-simple.
PROD HANA (cf target -s prod + cds bind): all four Tutorials rows status=ACTIVE, linkStatus=BROKEN, linkStatusOverride=null; ContentCurrent has a row only for abap-connectivity-daemon-simple.
DEV approuter: all four return 200 (x-content-source: cache).

Relationship to #2834

Same underlying failure mode as #2834 (ACTIVE catalog row with no servable PROD content). The split is by remediation: these four have content and need a PROD publish; #2834's four 404 everywhere with no content source and likely need retirement.

Status: attempted PROD publish — blocked at the Hugo-build step

Two rebuild-content.yml runs targeting prod both failed at "Publish tutorial content to HANA" with the same error:

Error: --slugs not found: s4hc-abap-environment-create-custom-api, private-link-gcp, btp-transport-management-cpi-01-use-case (available count=1407).
Check each slug is lowercase-canonical and its page exists. (hugoDir=hugo/public)

Run 1 (39141686034): default inputs — also wrong, it would have targeted DEV (environment defaults to dev).
Run 2 (39142124810): environment=prod, mode=slug-targeted, force-cap-refetch=true, force-publish=true. Same failure.

What this means: the publish step can't find hugo/public/tutorials/<slug>/ for these three. The build produced the full 1407-page catalog but not these slugs' pages — so the fetch→parse→Hugo pipeline is dropping them, which is almost certainly the same reason they were never published to PROD originally.

Refined per-slug findings

slug	PROD catalog	upstream `tutorials/<slug>/<slug>.md`	diagnosis
s4hc-abap-environment-create-custom-api	ACTIVE	exists (public + Contribution)	builds to 404 — pipeline drops the page
private-link-gcp	ACTIVE	exists (public + Contribution)	same
btp-transport-management-cpi-01-use-case	ACTIVE	exists (public + Contribution)	same
abap-environment-create-tile	ACTIVE	0 upstream matches + empty `title:` locally	no real source — retire like #2834 (dropped from this issue's publish set)

Catalog inclusion is purely status='ACTIVE' or status is null (build-catalog.js:26) — there is no separate publish flag — so all three ARE in the catalog. The page nonetheless never lands in hugo/public, pointing at a per-slug fetch/parse failure (parser rejects the page → no Hugo output → publish "not found"). abap-environment-create-tile's empty title is one such failure mode made visible.

Blocked — needs a decision / deeper investigation

A blind re-trigger won't fix this. Next step is one of:

Investigate the fetch/parse failure for the three valid slugs (run fetch-tutorials.ts --slugs <slug> --target hugo to completion and read why no hugo/public/tutorials/<slug>/ is emitted — likely a v2-parser rejection). Fix the source/parser, then re-publish.
Retire them too (flip PROD status→INACTIVE, same as Orphaned ACTIVE catalog rows: 4 tutorials 404 everywhere with no content source (IMS migration leftovers) #2834) if the content is genuinely not worth restoring.

I did NOT retire these — they have valid upstream source, so retirement would discard real content. Leaving that call to a maintainer.

Done regardless

Separately moved abap-environment-create-tile into the retire bucket (0 upstream source); it should be flipped INACTIVE with #2834's four.

Root cause found: `stepCount: 0` → validator rejects → never builds → never publishes

CI run 39142124810 fetched all three slugs fine, then the Validate tutorials step failed each with Invalid 'stepCount' value: 0. A tutorial that validates to 0 steps is never emitted to hugo/public, so the publish step reports "not found". Reproduced locally with composeTutorial() → STEP_COUNT 0.

stepCount = steps.length (render-frontmatter.ts:130), and parseV2Steps segments steps on H3 (### ) headings (see the comment in compose.ts:~81: "parseV2Steps's /^### (.+)$/ would otherwise return 0 steps"). Each slug trips this differently:

slug	`parser:`	`## Step` (H2)	`###` (H3)	why 0 steps
private-link-gcp	v2	5	0	steps authored as H2 (`## Step N:`); v2 parser only counts H3
s4hc-abap-environment-create-custom-api	missing	0	1	no `parser: v2` field → not parsed as v2
btp-transport-management-cpi-01-use-case	v2	0	0	no step headings at all — uses some other structure

These are upstream source-format defects in sap-tutorials/Tutorials, not a tutorials-ims code bug. They explain why these tutorials never reached PROD in the first place.

Fix (author-domain, per slug — PR to `sap-tutorials/Tutorials` + its `-Contribution`)

private-link-gcp — change the 5 ## Step N: headings to ### Step N:.
s4hc-abap-environment-create-custom-api — add parser: v2 to frontmatter and ensure steps are ### H3s (currently only 1 H3 — needs structural review).
btp-transport-management-cpi-01-use-case — add proper ### step headings; the source currently has no step structure the v2 parser recognizes (inspect for ACCORDION/OPTION/single-page layout).

Each is a genuine content edit that needs per-tutorial validation (not a bulk sed), ideally via the sap-tutorial-dual-pr skill so the fix lands in both the public and Contribution repos. After the source is fixed, re-run:

gh workflow run rebuild-content.yml --repo sap-tutorials/tutorials-ims --ref main \
  -f environment=prod -f mode=slug-targeted -f force-cap-refetch=true -f force-publish=true \
  -f slugs="<fixed-slug>"

and confirm linkStatus clears to OK.

Recommendation

These three should NOT be retired (unlike #2834) — they have real, salvageable content; they just need their step markup corrected upstream. Suggest handing to the owning authors or fixing via the dual-PR skill. Leaving #2833 open as an author content-fix task.

(Note: abap-environment-create-tile, originally grouped here, has no upstream source at all and was retired alongside #2834 — flipped PROD status→INACTIVE.)

private-link-gcp — fix PRs opened (heading-only, verified to parse to 5 steps):

Public source: fix(private-link-gcp): promote step headings to H3 so v2 parser counts steps (#2833) Tutorials#24253
Contribution: https://github.com/sap-tutorials/Tutorials-Contribution/pull/42174

Promotes the 5 ## Step N: headings to ### Step N:. Drift note: the two repos had diverged for this tutorial (different intro/frontmatter/section order), so the fix was applied to each repo against its own current content rather than mirroring one onto the other — only the 5 Step-heading lines change in each. After the public PR merges, re-run the slug-targeted PROD rebuild to publish.

The other two are NOT formatting-only and were left for author review:

s4hc-abap-environment-create-custom-api — missing parser: v2; it's an old v1-format tutorial (## Details section). Converting to v2 is a structural rewrite, not a heading tweak.
btp-transport-management-cpi-01-use-case — a 42-line "Scenario Overview" intro page (first of an 8-part series) with no steps at all (only ## Introduction). A v2 tutorial with no ### steps parses to 0 by design; making it publish needs a content/parser decision, not formatting.

@dennis-leslie

Author-decision tutorials — source-repo issues opened & assigned (both in sap-tutorials/Tutorials-Contribution, the author working repo):

s4hc-abap-environment-create-custom-api → https://github.com/sap-tutorials/Tutorials-Contribution/issues/42175 (assigned @dennis-leslie) — needs v2 migration (add parser: v2 + restructure ## Details into ### Step N: sections).
btp-transport-management-cpi-01-use-case → https://github.com/sap-tutorials/Tutorials-Contribution/issues/42176 (assigned @Anke2016) — stepless "Scenario Overview"; author decides whether to add a real step or treat as a series intro.

Summary of #2833 resolution:

private-link-gcp — fixed (heading-only H2→H3), PRs merged in both Tutorials + Tutorials-Contribution. Needs a slug-targeted PROD rebuild to publish (deploy not yet authorized).
The other two — handed to authors via the two issues above; they're structural/content calls, not formatting.
abap-environment-create-tile — no source; retired with Orphaned ACTIVE catalog rows: 4 tutorials 404 everywhere with no content source (IMS migration leftovers) #2834.

Once the private-link-gcp rebuild runs and the two author fixes land, all BROKEN entries from the original report are cleared. Leaving this open to track the two author issues + the pending private-link-gcp republish.

@dennis-leslie

✅ private-link-gcp published to PROD and verified live.

Rebuild run 39144678809 (environment=prod, slug-targeted, force-publish): success.
https://developers.sap.com/tutorials/private-link-gcp/ → 200 (was 404), serving real content.
PROD approuter confirms the same.

Its linkStatus will auto-clear from BROKEN→OK on the next URL-health run (no manual flip needed).

Remaining on this issue: the two author fixes — Tutorials-Contribution#42175 (@dennis-leslie) and #42176 (@Anke2016). Once those land and publish, #2833 can close.

Navigation Menu

Repository navigation

3 tutorials 404 on PROD — never published due to stepCount=0 (upstream step-heading format defects) #2833

Summary (corrected)

Affected tutorials

Root cause

Suggested fix

Verification

Relationship to #2834

Status: attempted PROD publish — blocked at the Hugo-build step

Refined per-slug findings

Blocked — needs a decision / deeper investigation

Done regardless

Root cause found: `stepCount: 0` → validator rejects → never builds → never publishes

Fix (author-domain, per slug — PR to `sap-tutorials/Tutorials` + its `-Contribution`)

Recommendation

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

3 tutorials 404 on PROD — never published due to stepCount=0 (upstream step-heading format defects) #2833

Description

Summary (corrected)

Affected tutorials

Root cause

Suggested fix

Verification

Relationship to #2834

Activity

jung-thomas commented on Oct 18, 2026

Status: attempted PROD publish — blocked at the Hugo-build step

Refined per-slug findings

Blocked — needs a decision / deeper investigation

Done regardless

jung-thomas commented on Oct 18, 2026

Root cause found: stepCount: 0 → validator rejects → never builds → never publishes

Fix (author-domain, per slug — PR to sap-tutorials/Tutorials + its -Contribution)

Recommendation

jung-thomas commented on Oct 18, 2026

jung-thomas commented on Oct 18, 2026

jung-thomas commented on Oct 18, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Root cause found: `stepCount: 0` → validator rejects → never builds → never publishes

Fix (author-domain, per slug — PR to `sap-tutorials/Tutorials` + its `-Contribution`)