fix(builder): a game dump Windows refuses to read says why and what to do, not "Permission denied" #641

Merged

HumanBean merged 1 commit from llun/Longshot:fix/nup-read-error into main 2026-11-15 03:25:39 +00:00

Conversation 2 Commits 1 Files changed 2 +194 -5

llun commented 2026-11-15 02:05:30 +00:00

Member

• Copy link
• Copy Markdown

Type: fix · Risk: low · Tested on: Windows 11 (the build reading the game files; no GPU involved) · Needs: none

Why

A player's build can stop at "Read the game files" with only nup.py stopped (exit status 1): PermissionError: [Errno 13] Permission denied. It reads like a folder permission problem, but it isn't one: Windows opened the game dump fine and then
refused to read one part of it. That happens when another program holds a lock on that part of the file, or when the
drive can't read it back (a bad spot on a disk, a USB drive that drops out). The player gets no hint of either, or of
what to do. See #295, where a player hit this partway through a 25.7 GB dump.

How to reproduce

Seen on: Windows 11 (any GPU), the launcher building nightly 170 (main @ 6c9edffe), and v3.0.0-rc.3 in #295
Settings and switches: defaults
Steps: have another process hold an exclusive byte-range lock (LockFileEx) on part of the .nup's romfs data, then
build from that .nup in the launcher
Expected: a message that says the file is locked by another program and what to do
Actual: nup.py stopped (exit status 1): PermissionError: [Errno 13] Permission denied

What changed

When the system refuses a read of the .nup's data, nup.py now stops with a message that names the file and the point
in it, says why (another program has that part locked, or the drive couldn't read it), and what to do. It gets the real
reason from the Windows error the C runtime kept, which Python's "Errno 13" hides.

• nx2/nup.py: Nup._data() is the one read of the package's data (inner_is_zstd, is_packed, copy_to). On an
  OSError it raises SystemExit(unreadable(...)). windows_error() reads the error with the C runtime's
  _get_doserrno, which is looked up when nup.py loads: importing ctypes after the failure ran file calls of its own
  that replaced the error. unreadable() gives one of three messages:
  • errors 32 and 33 (sharing or lock violation): another program has that part of the file locked; close it, or copy
    the .nup to another folder and build from the copy
  • errors 21, 23, 27, 30, 31, 1117 and 1392, or EIO on Linux: the drive could not read it; copy the .nup to another
    drive, and if Windows can't copy it either, check the drive or dump the game again onto another drive
  • anything else: it could not be read, with the error, and the same advice
    The header and TOC reads when the package opens are unchanged. Errors from writing the extracted files (the full
    drive in out_of_space()) still reach extract() as they did.
• nx2/test_nup_read_error.py (new, game-free): an ordinary read is unchanged. Each message comes out for its errors.
  The message names the file, not its folder. On Windows, a real lock held by another process gives the lock message
  with error 33.

Measurements

Nothing to measure: only the message of a failed read of the dump changes (a full read of a real dump through the changed reads matches main, see Testing).

Flags and settings

None

Testing

Tested:

• Windows 11, in the launcher, building nightly 170's tools from a real dump, with another process locking 1 MB of it
  at 247 MB (a romfs file early in the extraction). Main's nup.py stops with PermissionError: [Errno 13] Permission denied. This PR's nup.py stops with "Windows would not let the build read <the .nup> at 247 of 24435 MB: another
  program has that part of the file locked (Windows error 33). ..." The screenshots are in the first comment.
• The same dump read whole through the changed reads (nup.py --verify --title 1): 186,588 records, 159,537 unique
  extents, 0 bad, about 20 s, the same as main's nup.py on it.
• python -I -B tests/run_all.py on this PR @ 0f7d98dd (main @ f5718d03), Python 3.15 with llvm-mingw on PATH:
  491 passed, 18 failed, 79 skipped. Main @ f5718d03 on this PC: 491 passed, 17 failed, the same 17 (main's own here:
  test_appimage_player_build, test_bake_portability, test_cpm_discovery, test_crash_dialog, test_env_on,
  test_fpx_sticky, test_lift_cache, test_lift_cleanup_error, test_linux_preflight, test_make_game_cache,
  test_oot_state_tap, test_readback_late, test_spawn_emit, test_tested_configurations, test_vk_pgo,
  test_vram_budget_row, test_walk_key). The 18th, tests/test_longshot_ctl.py, timed out a 1 s log wait
  (Sessions.test_utf8_cursor_keeps_incomplete_characters) under the full run's load; alone it passes 3 of 3 here and
  on main, and this PR doesn't touch it. The new check passes.
• nx2/test_nup_read_error.py fails on main (the refused read comes out as the bare OSError) and passes here. All
  eight nx2/test_nup_*.py checks pass.

Not tested:

• A real drive error (a bad sector, a drive that drops out). It can't be made safely here. The game-free check covers
  its message through the Windows error numbers and Linux's EIO.
• Linux in a build. Nothing in the change is Windows-only except reading the Windows error, and the game-free check runs
  the same reads there.

Must be tested: None

Risks

What could break: a build from a .nup on another OS or Python, if Nup._data() changed an ordinary read. It doesn't:
it is the same read(), with tell() before it. The full verify above reads every file of a dump through it.

Turning it off: revert the commit

Compatibility: Nothing changes: saves, the options file, the caches, the vk ABI and the builder's tools are as they
were. Only the message of a failed read differs.

Issues

See #295

Checklist

Everyone

• One topic.
• The title is a Conventional Commit (type(scope): description) of the status line's type.
• Why gives the reason plainly and links the issues that fit (the tracker searched).
• Measurements has a verdict, or one line saying why there is nothing to measure.
• Testing names what was tested, what wasn't, and what must still be tested, where and how.
• Rebased on current main.
• python -I -B tests/run_all.py passes (any failure that also fails on main is named).
• No game files, dumps, build output or generated files.
• third_party/ untouched (a new folder with a PROVENANCE.md instead).
• The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

• AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
• Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen.
• A game-free test added for the fix, failing on main and passing here.

🤖 Generated with Claude Code

**Type:** fix · **Risk:** low · **Tested on:** Windows 11 (the build reading the game files; no GPU involved) · **Needs:** none ## Why A player's build can stop at "Read the game files" with only `nup.py stopped (exit status 1): PermissionError: [Errno 13] Permission denied`. It reads like a folder permission problem, but it isn't one: Windows opened the game dump fine and then refused to read one part of it. That happens when another program holds a lock on that part of the file, or when the drive can't read it back (a bad spot on a disk, a USB drive that drops out). The player gets no hint of either, or of what to do. See #295, where a player hit this partway through a 25.7 GB dump. ## How to reproduce **Seen on:** Windows 11 (any GPU), the launcher building nightly 170 (main @ 6c9edffe), and v3.0.0-rc.3 in #295 **Settings and switches:** defaults **Steps:** have another process hold an exclusive byte-range lock (`LockFileEx`) on part of the .nup's romfs data, then build from that .nup in the launcher **Expected:** a message that says the file is locked by another program and what to do **Actual:** `nup.py stopped (exit status 1): PermissionError: [Errno 13] Permission denied` ## What changed When the system refuses a read of the .nup's data, `nup.py` now stops with a message that names the file and the point in it, says why (another program has that part locked, or the drive couldn't read it), and what to do. It gets the real reason from the Windows error the C runtime kept, which Python's "Errno 13" hides. - nx2/nup.py: `Nup._data()` is the one read of the package's data (`inner_is_zstd`, `is_packed`, `copy_to`). On an `OSError` it raises `SystemExit(unreadable(...))`. `windows_error()` reads the error with the C runtime's `_get_doserrno`, which is looked up when nup.py loads: importing ctypes after the failure ran file calls of its own that replaced the error. `unreadable()` gives one of three messages: - errors 32 and 33 (sharing or lock violation): another program has that part of the file locked; close it, or copy the .nup to another folder and build from the copy - errors 21, 23, 27, 30, 31, 1117 and 1392, or EIO on Linux: the drive could not read it; copy the .nup to another drive, and if Windows can't copy it either, check the drive or dump the game again onto another drive - anything else: it could not be read, with the error, and the same advice The header and TOC reads when the package opens are unchanged. Errors from writing the extracted files (the full drive in `out_of_space()`) still reach `extract()` as they did. - nx2/test_nup_read_error.py (new, game-free): an ordinary read is unchanged. Each message comes out for its errors. The message names the file, not its folder. On Windows, a real lock held by another process gives the lock message with error 33. ## Measurements Nothing to measure: only the message of a failed read of the dump changes (a full read of a real dump through the changed reads matches main, see Testing). ### Flags and settings None ## Testing **Tested:** - Windows 11, in the launcher, building nightly 170's tools from a real dump, with another process locking 1 MB of it at 247 MB (a romfs file early in the extraction). Main's `nup.py` stops with `PermissionError: [Errno 13] Permission denied`. This PR's `nup.py` stops with "Windows would not let the build read <the .nup> at 247 of 24435 MB: another program has that part of the file locked (Windows error 33). ..." The screenshots are in the first comment. - The same dump read whole through the changed reads (`nup.py --verify --title 1`): 186,588 records, 159,537 unique extents, 0 bad, about 20 s, the same as main's `nup.py` on it. - `python -I -B tests/run_all.py` on this PR @ 0f7d98dd (main @ f5718d03), Python 3.15 with llvm-mingw on PATH: 491 passed, 18 failed, 79 skipped. Main @ f5718d03 on this PC: 491 passed, 17 failed, the same 17 (main's own here: test_appimage_player_build, test_bake_portability, test_cpm_discovery, test_crash_dialog, test_env_on, test_fpx_sticky, test_lift_cache, test_lift_cleanup_error, test_linux_preflight, test_make_game_cache, test_oot_state_tap, test_readback_late, test_spawn_emit, test_tested_configurations, test_vk_pgo, test_vram_budget_row, test_walk_key). The 18th, `tests/test_longshot_ctl.py`, timed out a 1 s log wait (`Sessions.test_utf8_cursor_keeps_incomplete_characters`) under the full run's load; alone it passes 3 of 3 here and on main, and this PR doesn't touch it. The new check passes. - `nx2/test_nup_read_error.py` fails on main (the refused read comes out as the bare `OSError`) and passes here. All eight `nx2/test_nup_*.py` checks pass. **Not tested:** - A real drive error (a bad sector, a drive that drops out). It can't be made safely here. The game-free check covers its message through the Windows error numbers and Linux's EIO. - Linux in a build. Nothing in the change is Windows-only except reading the Windows error, and the game-free check runs the same reads there. **Must be tested:** None ## Risks **What could break:** a build from a .nup on another OS or Python, if `Nup._data()` changed an ordinary read. It doesn't: it is the same `read()`, with `tell()` before it. The full verify above reads every file of a dump through it. **Turning it off:** revert the commit **Compatibility:** Nothing changes: saves, the options file, the caches, the vk ABI and the builder's tools are as they were. Only the message of a failed read differs. ## Issues See #295 ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen. - [x] A game-free test added for the fix, failing on `main` and passing here. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

llun added 1 commit 2026-11-15 02:05:30 +00:00

fix(builder): a game dump Windows refuses to read says why and what to do, not "Permission denied" ... 543459cbb5

A read of the .nup that the system refuses partway through (another program's lock on that part of the file, a drive
that cannot read it back) stopped the build at "Read the game files" with a bare "PermissionError: [Errno 13]
Permission denied". Python reports Windows errors 19 to 36 alike as errno 13, so nup.py now reads the Windows error the
C runtime kept (_get_doserrno) and says, with the file and where in it: another program has it locked (32, 33), the
drive could not read it (21, 23, 27, 30, 31, 1117, 1392, or EIO on Linux), or that it could not be read, each with what
to do. nx2/test_nup_read_error.py checks each message, and on Windows a real lock held by another process.

See #295

Co-Authored-By: Claude Opus 5.5 <[email protected]>

llun commented 2026-11-15 02:05:38 +00:00

Author

Member

• Copy link
• Copy Markdown

Screenshots: the launcher building nightly 170's tools from a real dump while another process locks 1 MB of it at 247 MB. Only nx2/nup.py differs between the two.

Before: main @ 6c9edffe

After: this PR @ 543459cb

Screenshots: the launcher building nightly 170's tools from a real dump while another process locks 1 MB of it at 247 MB. Only `nx2/nup.py` differs between the two. **Before: main @ 6c9edffe**  **After: this PR @ 543459cb** 

before-main-6c9edffe.png

40 KiB

after-pr-543459cb.png

55 KiB

llun changed title from WIP: fix(builder): a game dump Windows refuses to read says why and what to do, not "Permission denied" to fix(builder): a game dump Windows refuses to read says why and what to do, not "Permission denied" 2026-11-15 02:06:12 +00:00

llun scheduled this pull request to auto merge when all checks succeed 2026-11-15 02:41:14 +00:00

llun self-assigned this 2026-11-15 02:41:29 +00:00

llun removed their assignment 2026-11-15 02:41:30 +00:00

llun scheduled this pull request to auto merge when all checks succeed 2026-11-15 02:41:40 +00:00

llun force-pushed fix/nup-read-error from 543459cbb5 to 7baf5b7666 2026-11-15 03:13:25 +00:00 Compare

llun force-pushed fix/nup-read-error from 7baf5b7666 to 0f7d98ddf1 2026-11-15 03:23:02 +00:00 Compare

llun commented 2026-11-15 03:23:33 +00:00

Author

Member

• Copy link
• Copy Markdown

Rebased onto main @ f5718d03 (#629): the head is now 0f7d98dd. No conflicts, and the patch is unchanged (it replaces 7baf5b76, the same commit on b80a68f1).

python -I -B tests/run_all.py on 0f7d98dd, Windows 11: 491 passed, 18 failed, 79 skipped. Main @ f5718d03 on the same PC: 491 passed, 17 failed, the same 17 (named in Testing). The 18th, tests/test_longshot_ctl.py, timed out a 1 s log wait under the full run's load and passes 3 of 3 alone, here and on main. nx2/test_nup_read_error.py passes. The Testing section now gives this run instead of the one on 6c9edffe.

Open PRs that touch nx2/nup.py (#218, #546) change other parts of it; ours merges cleanly with both.

Rebased onto main @ f5718d03 (#629): the head is now **0f7d98dd**. No conflicts, and the patch is unchanged (it replaces 7baf5b76, the same commit on b80a68f1). `python -I -B tests/run_all.py` on 0f7d98dd, Windows 11: 491 passed, 18 failed, 79 skipped. Main @ f5718d03 on the same PC: 491 passed, 17 failed, the same 17 (named in Testing). The 18th, `tests/test_longshot_ctl.py`, timed out a 1 s log wait under the full run's load and passes 3 of 3 alone, here and on main. `nx2/test_nup_read_error.py` passes. The Testing section now gives this run instead of the one on 6c9edffe. Open PRs that touch `nx2/nup.py` (#218, #546) change other parts of it; ours merges cleanly with both.

HumanBean merged commit fad1a964cd into main 2026-11-15 03:25:39 +00:00

HumanBean deleted branch fix/nup-read-error 2026-11-15 03:25:39 +00:00

HumanBean referenced this pull request from a commit 2026-11-15 03:25:40 +00:00

fix(builder): a game dump Windows refuses to read says why and what to do, not "Permission denied" (#641)

madebyjordan referenced this pull request 2026-11-15 07:36:05 +00:00

feat(build): a new version's game files hard-linked from another game folder of the same .nup #360

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area/accessibility

Barriers for people with disabilities

  

area/audio

Sound and music

  

area/input

Controllers, keyboard, mouse

  

area/install

Installing, updating, building from your game

  

area/menu

In-game menu and settings

  

area/renderer

Vulkan renderer, shaders, effects

  

area/saves

Save files

  

area/upscaling

DLSS, FSR, frame generation

  

beanstalk: approved @ 1697603

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 2c5a62e

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 4fd82b7

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 64d6d09

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 6f91fae

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 70a78f9

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 8015c9a

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 8d361dc

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 9d8356e

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ abf2227

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ d82f202

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ e5f1e40

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ ee8ab5f

Set by Beanstalk for show; the farm's database is what counts

  

ci: approved

A maintainer approved CircleCI for this fork PR (sticky; removed after 14 quiet days)

  

good first issue

A good start for a new contributor

  

gpu/amd

AMD GPUs

  

gpu/igpu

Integrated GPUs

  

gpu/intel

Intel GPUs

  

gpu/nvidia

NVIDIA GPUs

  

help wanted

Extra hands or knowledge wanted

  

kind

bug

Something doesn't work as it should

  

kind

chore

Build, CI, dependencies, tidying

  

kind

docs

Documentation

  

kind

feature

A new feature or an improvement

  

kind

performance

Frame rate, frame time, loading, memory

  

kind

question

A question rather than a change

  

needs measurements

Waiting for before/after measurements

  

platform/linux

Affects Linux (a change for every system carries both Windows and Linux)

  

platform/macos

macOS (Apple silicon or Intel Macs)

  

platform/steam-deck

Steam Deck

  

platform/windows

Affects Windows (a change for every system carries both Windows and Linux)

  

preview

Maintainers: deploy a preview of this PR's website (read its changes first). Removed after the run.

  

priority

critical

Crashes, data loss, or blocks most players

  

priority

high

Important: next in line

  

priority

low

Nice to have

  

regression

Worked in an earlier build, broken in a newer one: highest priority, above other bugs

  

status

blocked

Waits on something else first

  

status

confirmed

Reproduced or agreed on

  

status

duplicate

Already reported or proposed

  

status

invalid

Not a problem in this project

  

status

needs-info

Waiting for more information from the reporter

  

status

wontfix

Will not be worked on

  

testing wanted

Wanted: a test on other hardware (posts a test request in #test-requests)

  

ci: approved

No labels

area/accessibility

area/audio

area/input

area/install

area/menu

area/renderer

area/saves

area/upscaling

beanstalk: approved @ 1697603

beanstalk: approved @ 2c5a62e

beanstalk: approved @ 4fd82b7

beanstalk: approved @ 64d6d09

beanstalk: approved @ 6f91fae

beanstalk: approved @ 70a78f9

beanstalk: approved @ 8015c9a

beanstalk: approved @ 8d361dc

beanstalk: approved @ 9d8356e

beanstalk: approved @ abf2227

beanstalk: approved @ d82f202

beanstalk: approved @ e5f1e40

beanstalk: approved @ ee8ab5f

ci: approved

good first issue

gpu/amd

gpu/igpu

gpu/intel

gpu/nvidia

help wanted

kind

bug

kind

chore

kind

docs

kind

feature

kind

performance

kind

question

needs measurements

platform/linux

platform/macos

platform/steam-deck

platform/windows

preview

priority

critical

priority

high

priority

low

regression

status

blocked

status

confirmed

status

duplicate

status

invalid

status

needs-info

status

wontfix

testing wanted

ci: approved

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

MagicBeanDev/Longshot!641

No description provided.