Ren'Py Steam Build Label Not Found After Freeze Persistent Schema Bump - How to Fix

Problem: Your Steam visual novel demo launches, then hard-crashes or returns to the main menu with Label 'chapter_3_hub' not found (or similar). Launcher “Run Project” in the editor still works. You bumped persistent_schema_v1.json mid–freeze week after a writer patch, but never regenerated label_inventory_v1.json or rebuilt the RPA archive on the depot you promoted.

Who is affected now: Teams running the 7-day Ren'Py build label and asset freeze in May–October 2026. The failure shows on packaged and Steam-installed builds—not when jumping labels inside the editor—because the shipped .rpa (or loose script bundle) does not contain labels that exist only in your dev tree.

Fastest safe fix: Regenerate label_inventory_v1.json from the same commit you ship → bump save_format_version with a save_incompatible migration label → run renpy.sh compile (or launcher Build Distributions) from a clean build/ folder → set gate6_steam_install: true in renpy_freeze_receipt_v1.json only after installed Steam smoke reaches the new label in under 30 seconds → re-promote fest_demo with a new build_label.

Direct answer

The traceback means the running build’s script archive does not define the label your jump or menu action targets. A persistent schema bump without a matching label inventory regen and full rebuild leaves Steam serving an old RPA while script.rpy on disk already references chapter_3_hub. Ren'Py does not hot-patch labels into a promoted depot—you must recompile, re-archive, and re-upload.

Why this issue spikes in May 2026

1. The Ren'Py freeze challenge introduced persistent_schema_v1.json—writers treat schema edits as “save fix only.”
2. Mid-freeze dialogue patches add jump chapter_3_hub without updating Monday’s inventory.
3. build.classification: demo excludes script files that still exist in dev but never entered the demo package list.
4. Branch promotion copies an RPA built before the schema bump—same class of drift as save-slot label mismatch.

Pair with 12 Free Defold GDevelop Ren'Py save-path audit resources for persistent-path discipline on the same promotion day.

Symptoms and search phrases

• Traceback: Label '…' not found on first play after Steam update; editor play OK.
• Main menu loads; Start Demo crashes within 30 seconds.
• Save/load jumps to a label missing from label_inventory_v1.json.
• persistent.save_format_version mismatch causes Restart() loop before gameplay.
• build_label on title does not match BUILD_RECEIPT row after hotfix.
• Autosave fires before demo_entry_label—loads invalid state.

Root causes (check in order)

1. label_inventory_v1.json stale — new labels not listed after writer merge.
2. Demo classification excludes script — chapter_3.rpy not in demo classification.
3. RPA archive not rebuilt — Steam depot still serves pre-bump scripts.rpa.
4. build.classification still all or release while fest needs demo.
5. Persistent defaults incompatible — old saves jump to removed labels.
6. config.developer true masks missing labels in editor only.
7. Playtest depot promoted instead of fest RPA—see playtest isolation.

Fastest safe fix path

Step 1 — Regenerate label inventory (Gate 1 replay)

From project root, list every label reachable in the demo route:

# Example — adjust path to your Ren'Py SDK
./renpy.sh . lint

Update label_inventory_v1.json:

{
  "schema": "label_inventory_v1",
  "project_version": "0.6.0-freeze-week",
  "demo_entry_label": "start_demo",
  "labels": [
    { "name": "start_demo", "reachable_in_demo": true, "file": "script.rpy" },
    { "name": "chapter_3_hub", "reachable_in_demo": true, "file": "chapter03.rpy" }
  ],
  "excluded": [
    { "name": "debug_cheats", "reachable_in_demo": false }
  ]
}

Pass: Every jump, call, and menu action in demo routes appears in labels[].
Fail: Orphan jump in chapter03.rpy but label only in dev-only file not in demo classification.

Step 2 — Align persistent schema and migration label (Gate 4)

Bump save_format_version in persistent_schema_v1.json and ship a visible migration:

{
  "schema": "persistent_schema_v1",
  "save_format_version": 3,
  "migration": {
    "on_version_mismatch": "jump save_incompatible",
    "message_label": "save_incompatible"
  }
}

In script.rpy:

label save_incompatible:
    "This demo was updated. Earlier saves cannot be loaded."
    $ persistent.save_format_version = 3
    jump start_demo

Pass: Old saves show message—not traceback.
Fail: Silent reset at wrong label → inventory still missing start_demo.

Writer rule: schema bump and inventory regen land in the same commit.

Step 3 — Clean compile and rebuild distributions

1. Delete stale output: build/, dist/, and old *.rpa under the game directory (backup first).
2. Confirm options.rpy / build.rpy classify rules include demo script files.
3. Run compile:

./renpy.sh . compile

4. Build desktop package with frozen build.classification: demo (see build classification freeze).
5. Verify new build_label on title screen matches receipt.

Pass: renpy.sh . compile exits 0; no “could not find label” in log.
Fail: Compile warns about unknown jump—fix before SteamPipe.

Step 4 — Steam install smoke (Gate 6)

On a machine that only has the Steam-installed build:

1. Launch from library (not developer folder copy).
2. Start demo → reach chapter_3_hub within 30 seconds.
3. Save slot 1 → quit → relaunch → load.
4. Confirm no traceback on cold boot.

Update renpy_freeze_receipt_v1.json:

{
  "schema": "renpy_freeze_receipt_v1",
  "build_label": "vn-nextfest-2026-05-24-rc2",
  "save_format_version": 3,
  "gates": {
    "gate1_label_inventory": true,
    "gate4_persistent_schema": true,
    "gate5_round_trip": true,
    "gate6_steam_install": true
  },
  "freeze_pass": true,
  "promotion_allowed": true
}

Do not set promotion_allowed: true until Gate 6 passes on the same build_label you upload.

Step 5 — Promote fest branch with new depot only

1. Upload rebuilt package to fest_demo (not playtest) per October Steamworks distribution spine.
2. Run Wednesday metadata diff—chapter count in store copy must match inventory.
3. Attach receipt beside BUILD_RECEIPT.

Verification checklist

• [ ] label_inventory_v1.json lists every demo-route label including post-patch hubs.
• [ ] save_format_version bumped with save_incompatible path tested.
• [ ] renpy.sh . compile clean on CI or release machine.
• [ ] New RPA timestamps after schema bump commit.
• [ ] Installed Steam build reaches chapter_3_hub in < 30 s.
• [ ] gate6_steam_install: true in freeze receipt.
• [ ] Store FAQ chapter scope matches inventory.

Prevention

1. Same-commit rule: persistent_schema_v1.json change → regen inventory → compile in one PR.
2. Freeze week moratorium on new labels unless producer restarts Gate 1.
3. CI grep: fail build if jump targets not in inventory JSON (simple script).
4. Pair narrative patches with local voice-notes workflow—draft labels before they enter script.rpy.
5. Separate playtest vs fest build_label rows in isolation playbook.

Troubleshooting

FAQ

Do I need to rename the label in dialogue only?
If the label name changed, update every jump and menu action, then regen inventory. Renaming without rebuild leaves Steam on old archives.

Is this the same as save-slot UI mismatch?
Related promotion failure—save-slot case study covers UI slot numbers vs disk paths; this help covers missing script labels in the RPA.

Can I patch only persistent without rebuilding?
No for missing-label tracebacks. Persistent fixes alone do not add chapter_3_hub to the shipped archive.

What about Steam Cloud saves?
If Cloud is enabled, document wipe policy when save_format_version bumps—local-only demos should say so in FAQ parity.

Related links

• 7-Day Ren'Py Steam Build Label and Asset Freeze Challenge (2026)
• 12 Free Defold GDevelop Ren'Py Save-Path Audit Resources
• Mismatched Save Slot Labels After Branch Promotion
• Wednesday Demo Build Smoke Ritual
• Local Voice Notes to Quest Drafts (narrative QA)
• Ren'Py — Building distributions
• Ren'Py — Persistent data

Regenerate the inventory the same day you bump save_format_version—then Steam players see the labels your writers already wrote.