nxnative-easy/docs/agents/symptoms.md

# Symptom index

One line per symptom in the [subsystem references](../reference/): what you see (an assertion, a `[RED]` line, an abort or crash site, a visible result) and the entry that explains it. Search this page for the text in your log first (`grep -i` the function name, the `[RED]` text or the address form), then read the entry and the game notes it names. Generated by `dm/tools/docs_symptoms.py` from the entries' Symptom bullets: change the entry, then run it.

## Packing

- the first extraction stops with `nx_extract exit code 131` and `.NET location: Not found`, even though `dotnet` is on `PATH`. The shader translator can fail the same way. → [Homebrew .NET is on PATH but apphosts cannot find the runtime](../reference/packing.md#homebrew-net-is-on-path-but-apphosts-cannot-find-the-runtime)
- packing succeeds, but `unzip -t` or Python's `ZipFile.testzip()` reports a bad CRC for a large deflated file. → [A streamed file changes size and the IPA fails its CRC check](../reference/packing.md#a-streamed-file-changes-size-and-the-ipa-fails-its-crc-check)
- `decompress NSZ` stops immediately with `nsz: error: unrecognized arguments: --keys …`. → [NSZ decompression rejects `--keys`](../reference/packing.md#nsz-decompression-rejects---keys)

## Rewriter

- an updated game loses a needed cut because its NSO build ID changed, although the relevant code still matches a verified version; the rewriter reports `[RED] function patch ... skipped` when that match cannot be established. → [Function-matched cuts for unregistered builds](../reference/rewriter.md#function-matched-cuts-for-unregistered-builds)
- `jump table <addr>` assertion in `patch_nso.py`, in a Unity / IL2CPP `main`. → [Offset jump tables through x18 read at rewrite time](../reference/rewriter.md#offset-jump-tables-through-x18-read-at-rewrite-time)
- `jump table <addr>` assertion in `patch_nso.py`, in a `subsdk`. → [Offset jump tables with the bounds check on another register](../reference/rewriter.md#offset-jump-tables-with-the-bounds-check-on-another-register)
- `jump table <addr>` assertion where the index is a copy made before the check (`mov w0,w18`, then 41 instructions holding two other jump tables on `x0`, then `cmp w18,#4; b.hi; ldrsw x18,[x11,x0,lsl #2]; add x18,x18,x11; br x18`). → [Index copied before the bounds check](../reference/rewriter.md#index-copied-before-the-bounds-check)
- `jump table <addr>` assertion in `patch_nso.py` on an offset table whose index is checked with a 64-bit compare (`cmp x22, #0x10; …; b.hi; adrp x18 + add x18; mov x0, x18; ldrsw x18, [x0, x22, lsl #2]; add x18, x18, x0; br x18`). → [64-bit bounds check of the index](../reference/rewriter.md#64-bit-bounds-check-of-the-index)
- `jump table <addr>` assertion in a Unity / IL2CPP `main` whose dispatch checks a fresh mask of another register than the one it indexes with. → [Index masked in the block that branches to the dispatch](../reference/rewriter.md#index-masked-in-the-block-that-branches-to-the-dispatch)
- `jump table <addr>` assertion on an offset table whose base was set far back (`cmp w18,#5; b.hi; ldrsw x18,[x24,x18,lsl #2]; add x18,x18,x24; br x18`). → [Offset table base set far back in the function](../reference/rewriter.md#offset-table-base-set-far-back-in-the-function)
- `jump table <addr>` assertion on an offset table whose base was set far back and moved through other registers (`ldrb w18,[x14]; sub w18,w18,#1; cmp w18,#6; b.hi; ldrsw x18,[x7,x18,lsl #2]; add x18,x18,x7; br x18`). → [Far table base passed through other registers](../reference/rewriter.md#far-table-base-passed-through-other-registers)
- `jump table <addr>` assertion, entries relative to an `adr`. → [Offset tables relative to an adr](../reference/rewriter.md#offset-tables-relative-to-an-adr)
- `jump table <addr>` assertion on a byte table indexed by x30 (`adr x18, #L; ldrb w30, [x14, x12]; add x18, x18, x30, lsl #2; br x18`). → [Byte tables indexed by x30 (capstone register names)](../reference/rewriter.md#byte-tables-indexed-by-x30-capstone-register-names)
- `jump table <addr>` assertion on a byte table whose `add` is far from the `br` (`adr x18,#L; ldrb w0,[x17,x15]; add x18,x18,x0,lsl #2`, then 17 register moves before `br x18`). → [Byte tables whose add is far from the br](../reference/rewriter.md#byte-tables-whose-add-is-far-from-the-br)
- `jump table <addr>` assertion in `patch_nso.py`, in a Unity / IL2CPP `main`, at a `blr x18`. → [Indirect calls through x18](../reference/rewriter.md#indirect-calls-through-x18)
- `jump table <addr>` assertion on a `br x18` with no table in front of it. → [Indirect tail calls through x18 in IL2CPP thunks](../reference/rewriter.md#indirect-tail-calls-through-x18-in-il2cpp-thunks)
- `jump table 53e9c` while rewriting Warm Snow 2.1.4's Unity IL2CPP `main`. → [Loaded method-pointer tail call before an error block](../reference/rewriter.md#loaded-method-pointer-tail-call-before-an-error-block)
- job system hangs; a queue claims thousands of tasks but every slot is empty. → [Exit stub order in exclusive windows](../reference/rewriter.md#exit-stub-order-in-exclusive-windows)
- `branch into window <addr>` assertion. → [Out-of-line retry blocks of atomic updates](../reference/rewriter.md#out-of-line-retry-blocks-of-atomic-updates)
- branches to an `ldxr … stxr` loop's head landed mid-window. → [A window never spans a second exclusive load](../reference/rewriter.md#a-window-never-spans-a-second-exclusive-load)
- `AssertionError: 0x…` in `site_window` on an `adrp` inside an exclusive window (`ldaxr x9,[x9]; cmp x9,x25; b.ne out; adrp x10 + add x10` (the same address again, for the store); `mov x18,x26; stlxr w9,x8,[x10]`, then loads and `cbnz w9` back). → [adrp inside an exclusive window](../reference/rewriter.md#adrp-inside-an-exclusive-window)
- `B()` assertion at a spin wait: a branch into the patch area beyond the ±128 MB a `b` reaches. → [Halfword jump table landing pads sized to the largest entry](../reference/rewriter.md#halfword-jump-table-landing-pads-sized-to-the-largest-entry)
- `B()` range assertion in `patch_nso.py` (`site_plain`), only for one module. → [Patch area before the module base for a large bss](../reference/rewriter.md#patch-area-before-the-module-base-for-a-large-bss)
- `frame step state page` assertion when a `FRAME_STEP` profile is added to a module with a large BSS. → [Frame-step state with a front patch area](../reference/rewriter.md#frame-step-state-with-a-front-patch-area)
- `B()` range assertion, then `patch area of … bytes does not fit in the … before the base`. → [Patch area right before the base for a long text](../reference/rewriter.md#patch-area-right-before-the-base-for-a-long-text)
- `observation gate neither at a function entry nor after a bl`; `observation gate neither at a function entry, after a bl nor before a call` on an epilogue. → [Observation gates where x9–x17 are dead](../reference/rewriter.md#observation-gates-where-x9x17-are-dead)
- `jump table <addr>` assertion on an ordinary byte table near the start of the text (`adr x18; ldrb w0,[x17,x16]; add x18,x18,x0,lsl #2; br x18`). → [Code before the first unwind entry is one function](../reference/rewriter.md#code-before-the-first-unwind-entry-is-one-function)
- the rewrite never finishes, the Mac swaps, the rewriter's footprint reaches 100 GB. → [Long functions analysed in pieces](../reference/rewriter.md#long-functions-analysed-in-pieces)
- `KeyError` at `site_br` for a `br x18` that is an ordinary byte jump table. → [Disassembly goes on after undecodable words](../reference/rewriter.md#disassembly-goes-on-after-undecodable-words)
- `RuntimeError: 788 ldr x18, #0xd1eb0` in `patch_nso.py`, or any rewrite site in data. → [Data blocks at the start of the text](../reference/rewriter.md#data-blocks-at-the-start-of-the-text)
- `jump table <addr>` assertion in `patch_nso.py`, in a Unity / IL2CPP `main`, at an `alloca` (`mov sp, x18`). → [Stack pointer writes through x18](../reference/rewriter.md#stack-pointer-writes-through-x18)
- `CRASH sig=10 addr=0` on an `stp` relative to `sp`, with `sp` not a multiple of 16 (`main+0x2bbba4`, `sub sp, sp, #0xc0` then `stp d15, d14, [sp, #0x60]` with sp ending in `…9dc`). → [Stack arguments reserved with sub sp, sp, xN](../reference/rewriter.md#stack-arguments-reserved-with-sub-sp-sp-xn)
- SIGILL / trap on a system register read. → [System register reads that macOS traps](../reference/rewriter.md#system-register-reads-that-macos-traps)
- every pointer in `.data` / the GOT is a module offset, crashes everywhere. → [Packed relative relocations (DT_RELR)](../reference/rewriter.md#packed-relative-relocations-dt_relr)

## Memory and address space

- large resources silently skipped, later a null deref where the resource is used; also visible as `SetHeapSize` asking for much less than the pool. → [Partitioning the guest block between alias region, stacks and heap](../reference/memory.md#partitioning-the-guest-block-between-alias-region-stacks-and-heap)
- `SetHeapSize OOM: req 0x600000 > cap 0`, followed by an SDK abort in `nninitStartup` on the first provisional boot. → [Provisional Unreal layout leaves no heap](../reference/memory.md#provisional-unreal-layout-leaves-no-heap)
- `nnMain` returns right after `nv::InitializeGraphics`, with no error (Hyrule Warriors: Age of Calamity); `[mem] SetHeapSize … + modules … > app pool` (Monster Hunter Rise), `[mem] SetHeapSize … + modules 0x5c00000 > app pool` (Catherine: Full Body); `SetHeapSize` asks for almost the whole application pool and fails at boot (Metroid Dread: 0xc9400000, larger than the heap region); the memory pool for the game's 96 MB GPU heap has no storage (`MemoryPoolInitialize` red line), then a null read at `main+0x2eb954` (Catherine: Full Body); heap allocations fail late in a busy scene. → [Heap sized from the application pool less used memory](../reference/memory.md#heap-sized-from-the-application-pool-less-used-memory)
- `SetHeapSize OOM: req 0x120000000 > cap 0xd0000000`, then `Break#1 reason=0` in `nninitStartup`, with a backtrace through `nn::os::SetMemoryHeapSize` (`sdk+0x967a4`). → [A heap request beyond the heap region returns ResultOutOfMemory](../reference/memory.md#a-heap-request-beyond-the-heap-region-returns-resultoutofmemory)
- `StandardAllocator::Initialize` aborts in `nninitStartup` (Fire Emblem Engage); `nn::diag` abort in `StandardAllocator::Initialize(void *, size_t, bool)` from `nninitStartup` (`sdk+0x2f98e4` ← `main+0x5b69e0`, Big Brain Academy: Brain vs. Brain). → [Virtual address memory follows the NPDM's system resource](../reference/memory.md#virtual-address-memory-follows-the-npdms-system-resource)
- the first `AllocateAddressRegion` fails with 0x1803; `StandardAllocator::Initialize` aborts in `nninitStartup` (an `nn::diag` abort; the NSP script's heap check reports "the host stopped before nnMain"); the alias region fills in minutes; regions a game reserves later fail (Size-aligned regions exhaust the alias address space, The movie player's own StandardAllocator). → [The SDK's address-region node area](../reference/memory.md#the-sdks-address-region-node-area)
- a null-based write minutes into play, at the pool size minus 0x20 (Engage: a write to `NULL + 0x1fffe0`, `addr=0x1fffe0` at `main+0x9a4664`); NULL index pointers written on several job threads at once (`main+0xdb0ad4`, `0xdaea58`, `0xdadb5c`), with 32-bit mesh indices turning up inside texture objects. → [Size-aligned regions exhaust the alias address space](../reference/memory.md#size-aligned-regions-exhaust-the-alias-address-space)
- a cut engine region still does not fit; two large regions lose up to 1 GB each to alignment, depending on where `mmap` put the guest block (Absolum); the region comes 0.69 GB past the 1 GB node area, at the next 1 GB boundary (Paper Mario: The Thousand-Year Door). → [1 GB alignment of regions of 1 GB and more](../reference/memory.md#1-gb-alignment-of-regions-of-1-gb-and-more)
- a write at NULL + 0x3fffe0 (a 4 MB pool − 0x20) at `main+0x48b770`, about six minutes into the prologue, with Unity's `ALLOC_CACHEOBJECTS_THREAD` allocator in x19; the `[mem]` high-water mark at +4.26 GB of the 4.375 GB alias region while 1.26 GB is mapped (Sea of Stars). → [Size-class alignment doubles Unity's regions](../reference/memory.md#size-class-alignment-doubles-unitys-regions)
- nothing aborts at startup as with Unity 2022.3, but the provisional profile gave a 1 GB block and a 256 MB alias region while Unity maps 1.5 GB in the first room. → [Unity 6 takes its memory with no StandardAllocator and no heap](../reference/memory.md#unity-6-takes-its-memory-with-no-standardallocator-and-no-heap)
- `nn::diag` abort from `StandardAllocator::Initialize` long after `nninitStartup`, right after the first Vulkan query pool (`sdk+0x12dad0` ← `main+0x62c52c`). → [The movie player's own StandardAllocator](../reference/memory.md#the-movie-players-own-standardallocator)
- `StandardAllocator::Initialize` aborts in `nninitStartup` (Pokémon Legends: Z-A: `main+0x1b2e690`); `nn::diag` abort at `sdk+0x11ff34` (`StandardAllocator::Initialize`) in `nninitStartup`, SDK 15.3.2, called from `main+0x31370c` (Paper Mario: The Thousand-Year Door). → [StandardAllocators over 12 to 62 GB of address space](../reference/memory.md#standardallocators-over-12-to-62-gb-of-address-space)
- `nn::diag` abort at `sdk+0x12dad0` in `nninitStartup`, called from `main+0x756310`. → [.NET NativeAOT malloc and the GC region range](../reference/memory.md#net-nativeaot-malloc-and-the-gc-region-range)
- the game aborts in its static initialisers, before `nnMain`, when its own 62 GB address region fails (`main+0x37c9bd0`, `AllocateAddressRegion(&p, 0xf80000000)` at `main+0x37c9a5c`). → [A 62 GB page allocator behind `nu::VirtualAllocHook`](../reference/memory.md#a-62-gb-page-allocator-behind-nuvirtualallochook)
- the game calls `exit(1)` in `nninitStartup` (Octopath Traveler 0: `main+0x12e74`); `nn::diag::Abort` from `main+0x352fbec` (Unreal's fatal error) after the first commit, `AllocateMemoryPages(0, 2 MB)` while the RHI starts (`main+0x353ff8c`, result 0xe03) (Pikmin 4); a crash in `NumberLineAllocator::Compaction` at boot (DRAGON QUEST XI S, region option 4224). → [Unreal's engine address region and its options](../reference/memory.md#unreals-engine-address-region-and-its-options)
- a null read in the out-of-memory report at `main+0x1005824` when the engine region is smaller than the allocator's pools (Octopath Traveler 0). → [Unreal's FMallocBinned3 replaced by the host allocator](../reference/memory.md#unreals-fmallocbinned3-replaced-by-the-host-allocator)
- an abort right at `nnMain`, under `nn::os::CreateThread` → `ThreadManagerImplByHorizon::MapAliasStack` → `StackGuardManager::MapAtRandomAddress`; with the log line, `[RED] MapMemory refused (0xd401): <stack region> <- <address outside the guest block>`. → [Thread stacks from the host's Unreal heap](../reference/memory.md#thread-stacks-from-the-hosts-unreal-heap)
- `nn::diag` abort from `main+0x11bc`, no message, in the first battle, with about 1 GB mapped (FINAL FANTASY RESONANCE with DRAGON QUEST VII Reimagined's 2 GB region). → [Unreal 5.6's page allocator never gives address space back](../reference/memory.md#unreal-56s-page-allocator-never-gives-address-space-back)
- write to `0x268` right after the title screen (`main+0x5d6708`, a constructor whose `this` is `0x200`). → [Ring heaps cut from a pool at 64 KB alignment](../reference/memory.md#ring-heaps-cut-from-a-pool-at-64-kb-alignment)
- C++ exception aborts in `nn::ro::detail::GetExceptionInfo`. → [`svcQueryMemory` must report each module's real layout](../reference/memory.md#svcquerymemory-must-report-each-modules-real-layout)
- `MapPhysicalMemory` faults on part of a page. → [`MapPhysicalMemory` in 16 KB host pages](../reference/memory.md#mapphysicalmemory-in-16-kb-host-pages)
- the alias region's mapped total runs past the application pool in the first minute. → [Maps past the application pool fail as on Horizon](../reference/memory.md#maps-past-the-application-pool-fail-as-on-horizon)
- a write through a null pointer at +0x1c0 during startup. → [`GetInfo(UserExceptionContextAddress)` returns a real buffer](../reference/memory.md#getinfouserexceptioncontextaddress-returns-a-real-buffer)
- a null-pool buffer even with virtual pools working (Virtual memory pools mapped onto one physical pool). → [A null-pool buffer from a game heap that ran out](../reference/memory.md#a-null-pool-buffer-from-a-game-heap-that-ran-out)
- a model load exhausts its resource heap: a null `operator new` at the world load, or `BufferInitialize: pool has no storage` followed by a null-pool crash. → [Model heaps sized by the host's command record sizes](../reference/memory.md#model-heaps-sized-by-the-hosts-command-record-sizes)
- the frames stop at the first loading screen, a graphics worker at 100% CPU (17 s in, `UnityGfxDeviceWorker` running, the main thread waiting on a condition variable, no red line). → [Unity's GPU pool block allocation spins at size 0](../reference/memory.md#unitys-gpu-pool-block-allocation-spins-at-size-0)
- SIGBUS inside a host hook (`snprintf` under `mount_ex` / `h_fs_MountSave`), then the process hangs (Super Mario 3D World + Bowser's Fury); SIGBUS inside Metal (`AGCDeserializedReply`, an AGX compiler block) at an address in the guest stack region (Breath of the Wild). → [Host calls on small guest stacks](../reference/memory.md#host-calls-on-small-guest-stacks)
- the iPhone app is killed for memory; resident memory grows steadily (about 0.2 MB a frame) while the residency set and the texture counts stay flat. → [Deferred-release drain without an autorelease pool](../reference/memory.md#deferred-release-drain-without-an-autorelease-pool)
- travelling produces a brief multi-GB footprint spike, then memory returns to its earlier level; periodic memory lines can miss the peak. Upload diagnostics show many swapped-out blocks still alive in one batch. → [Upload staging grows within one rendering submission](../reference/memory.md#upload-staging-grows-within-one-rendering-submission)
- GPU memory grows with repeated `nvnTextureReadTexels` calls on a long-lived game thread, even after each readback completes. → [GPU readback without an autorelease pool](../reference/memory.md#gpu-readback-without-an-autorelease-pool)

## Threads

- a parent returns from `StartThread` before a newly runnable higher-priority child pinned to its core finishes its work (deterministic regression, not attributed to a game failure). → [Starting a higher-priority thread on the caller's core](../reference/threads.md#starting-a-higher-priority-thread-on-the-callers-core)
- per-core job queues never drained. → [Core mask changes move the ideal core into the new mask](../reference/threads.md#core-mask-changes-move-the-ideal-core-into-the-new-mask)
- crash indexing a per-core table with a huge offset (index −2). → [Ideal core −2 resolves to the process default core](../reference/threads.md#ideal-core-2-resolves-to-the-process-default-core)
- the main thread waits forever on an event right after `nnMain` starts, with only three or four threads created; `DM_THR=1` shows no `CreateThread` for the thread it waits on. → [Free thread count (`svcGetInfo` type 24)](../reference/threads.md#free-thread-count-svcgetinfo-type-24)
- in garbage-collected titles (Unity / IL2CPP), live objects freed, with their finalizers releasing native resources. → [Pausing threads and reading their context for garbage collectors](../reference/threads.md#pausing-threads-and-reading-their-context-for-garbage-collectors)
- crashes around movie changes in the game's own player threads, about one run in two: `SignalEvent` → `MultiWaitImpl::NotifyAndWakeupThread` on a null MultiWait at address 0x20; `WaitAny` walking freed holders; a worker reading a freed object at `main+0x225338`. The other way round, a handoff that waits too widely: a black screen at boot that never loads a texture (`packaged textures: first uploads 0`), or a load that never ends behind an animated loading screen, with the thread dump's `same-core handoffs N, total T ms` larger than the run itself. → [Same-core wake handoffs](../reference/threads.md#same-core-wake-handoffs)
- several threads crash at once and the dumps interleave, then the process hangs instead of exiting. → [Simultaneous crashes of several threads](../reference/threads.md#simultaneous-crashes-of-several-threads)
- none seen; found while investigating Fire Emblem Engage's demo crash, which it did not change (that was the address-space shortage, Size-aligned regions exhaust the alias address space). → [`SignalToAddress` type 2 with count ≤ 0](../reference/threads.md#signaltoaddress-type-2-with-count--0)
- a 64-bit wait could return at once or block when it should not (not met in a game). → [`WaitForAddress` type 3: 64-bit wait if equal](../reference/threads.md#waitforaddress-type-3-64-bit-wait-if-equal)
- a PhysX worker crashes in a task's `removeReference` with a null task manager, right as the game switches to 30 fps (`pc=main+0x10ccf28`, `lr=main+0x13c236c`); on the iPhone and in 2 of 5 Mac runs, in every Mac run with 12 busy loops loading the CPU. → [Late PhysX task destructor after the unlock](../reference/threads.md#late-physx-task-destructor-after-the-unlock)
- a 30 Hz game thread runs at 27 Hz, and whatever it paces comes out slow (cutscenes at 36 ms per frame instead of 33.3; gameplay was fine at 60). → [Timer slack in guest sleeps (`sleep_precise`)](../reference/threads.md#timer-slack-in-guest-sleeps-sleep_precise)
- a guest thread keeps a core at 100% with billions of `SleepThread` calls. → [Sleeps under 20 µs take the yield path](../reference/threads.md#sleeps-under-20-µs-take-the-yield-path)
- a loading screen sits for a minute with the CPU nearly idle; one thread yields thousands of times a second, every yield a back-off sleep (the power line's top yielder, with as many back-off sleeps). → [Yields that make progress return at once (`thr_yield`)](../reference/threads.md#yields-that-make-progress-return-at-once-thr_yield)
- a host helper thread aborts when signalling a destroyed `SystemEvent`; repeated `vi::GetDisplayVsyncEvent` calls double the event's tick rate. Rapid replacement can abort with `too many vsync events`, or a retired vsync worker can signal another service's event at reused storage. → [Service-event producers follow the binding lifetime](../reference/threads.md#service-event-producers-follow-the-binding-lifetime)
- the main thread waits forever on a job's done event at boot while every worker sleeps, two of them on one event (`main+0x1426c` waiting on `Job::m_doneEvent`); 4 of 6 Mac runs. → [One auto-clear event shared by a pool's workers](../reference/threads.md#one-auto-clear-event-shared-by-a-pools-workers)
- abort in `os::WaitSystemEvent` under `oe::PopNotificationMessage` (The Legend of Zelda: Link's Awakening); one guest thread at about 1000 ms/s on the iPhone only, the phone hot, CPU energy 5–7 W (Monster Hunter Rise's `MessageSuperviseThread`, priority 32, in the `[nvn] threads` lines). → [The oe notification event and its queue](../reference/threads.md#the-oe-notification-event-and-its-queue)
- Paper Mario: The Thousand-Year Door 1.0.1 stays black before its first frame. The main thread stops at `main+0x32796c`, after starting `SYS_Notification`; the priority-28 notifier is in `oe::PopNotificationMessage`, while the priority-44 main thread waits for its same-core wake handoff. → [Native HLE waits release the guest core](../reference/threads.md#native-hle-waits-release-the-guest-core)

## Services and SDK calls

- `sm::Initialize` aborts right after `ConnectToNamedPort` (SVC 0x1F) and `SendSyncRequest` (0x21); abort inside `nn::sm::Initialize`, the log showing `SVC 0x1f` (ConnectToNamedPort, port name `sm:`) and `SVC 0x21` answered by placeholders, then an `nn::diag` abort; abort with no message at start-up in a service call the host has no hook for (`Break` from `sdk+…` with an `nn::diag` backtrace). → [SDK calls that open a system service through sm](../reference/services.md#sdk-calls-that-open-a-system-service-through-sm)
- a game update aborts at boot where the base game ran. → [A game update imports SDK calls the base game did not](../reference/services.md#a-game-update-imports-sdk-calls-the-base-game-did-not)
- abort in `sm::Initialize` under `sf::hipc::InitializeHipcServiceResolution`, right after the first frames (from `main+0x5b8198`). → [Game-linked HIPC clients of system services](../reference/services.md#game-linked-hipc-clients-of-system-services)
- a call the host hooks under its newer name reaches the SDK's own code on an older game. → [Older SDK names for the same calls](../reference/services.md#older-sdk-names-for-the-same-calls)
- abort in `sm::Initialize` under `nn::friends::GetBlockedUserList` after the opening movie. → [SDK 4's `friends::GetBlockedUserList` without a `Uid`](../reference/services.md#sdk-4s-friendsgetblockeduserlist-without-a-uid)
- the first loading screen never ends; `DM_FS=1` shows `save:/system` "not found" and no `fs mount save`. → [SDK 6's `account::OpenPreselectedUser` returns a Result](../reference/services.md#sdk-6s-accountopenpreselecteduser-returns-a-result)
- IL2CPP "Could not open …/global-metadata.dat" (then a crash in its logger). → [The SDK's own `fs::IsMounted` reads an empty mount table](../reference/services.md#the-sdks-own-fsismounted-reads-an-empty-mount-table)
- Addressables never start (no `StreamingAssets/aa/settings.json` in the `DM_FS=1` output at all), then a null asset crash (`main+0x31100ec`). → [C library path checks ask the file system's limits](../reference/services.md#c-library-path-checks-ask-the-file-systems-limits)
- an Atk task aborts in a `switch` default (`UnexpectedDefaultImpl`, then `AbortImpl`) while a stream sound loads. → [Paths with `.` and `..` components](../reference/services.md#paths-with--and--components)
- a long black screen at boot with nothing in the log (Engage: about 17 s on the Mac, 32 s on an iPhone); sampling the process (`sample <pid> 3`) shows `getxattr` under `path_component` at the top of stack. → [RomFS lookups on large directories](../reference/services.md#romfs-lookups-on-large-directories)
- `[RED] fs ReadFile into … failed at +0 (EFAULT): VM region … protection 1`, now and then. → [ReadFile into write-protected texture pool pages](../reference/services.md#readfile-into-write-protected-texture-pool-pages)
- `fs … not found` lines with `DM_FS=1`. → [File-not-found noise from optional paths](../reference/services.md#file-not-found-noise-from-optional-paths)
- a missing `fs::DeleteDirectory`; undefined `nn::fs::` / `nn::account::` imports with no hook, found from the import list (Listing a game's unhooked imports before they are met) before they were met. → [Directory, file data cache and save-thumbnail calls](../reference/services.md#directory-file-data-cache-and-save-thumbnail-calls)
- the SDK's own code opened fsp-srv and aborted, leaving the save writes uncommitted. → [`fs::Commit` with a list of mounts](../reference/services.md#fscommit-with-a-list-of-mounts)
- a failed write in one independent save can make another save's next `Commit` fail and discard its successful changes; the damaged save may then commit its truncated working file. → [Save-write failures stay with their backing transaction](../reference/services.md#save-write-failures-stay-with-their-backing-transaction)
- SIGSEGV at address 0 in `nn::fs::GetSaveDataSizeMax`, about 13 minutes into a new game. → [Save data size queries](../reference/services.md#save-data-size-queries)
- each aborted in `sm::Initialize` or read a null applet proxy, one per boot. → [Cache storage and other titles' save data](../reference/services.md#cache-storage-and-other-titles-save-data)
- the island lives in device save data, which the host did not mount. → [Device save data on the account save's directory](../reference/services.md#device-save-data-on-the-account-saves-directory)
- every boot asks to pick a Mii again (`DM_FS=1`: `UserSave:/userdata.dat` not found although the host save has it). → [Device and account save data as two saves](../reference/services.md#device-and-account-save-data-as-two-saves)
- abort in `fs::detail::GetFileSystemProxyServiceObject` under `fs::QueryMountSystemDataCacheSize` (`main+0x8f23bc`). → [System data stand-in for the MiiModel archive](../reference/services.md#system-data-stand-in-for-the-miimodel-archive)
- DLC the player owns is not unlocked. → [Add-on content from `DM_AOC_DIR`](../reference/services.md#add-on-content-from-dm_aoc_dir)
- SIGSEGV in `crypto::detail::CbcModeAes128Helper::DecryptBlocks` with a null destination (`main+0x8737e8`, right after `aoc:` is mounted). → [Add-on content mount cache sized as RomFS working memory](../reference/services.md#add-on-content-mount-cache-sized-as-romfs-working-memory)
- SIGBUS in `__vfprintf` under `aoc_load`, from `h_aoc_Count` (a store to `0x…67ff0`, right below a page of the guest thread's stack). → [Add-on content queries on a small guest stack](../reference/services.md#add-on-content-queries-on-a-small-guest-stack)
- buttons and menus work, the sticks do nothing in play (Super Mario Odyssey: its first hint, "Look Around", waited forever); an `nn::diag` abort with Result 0x2aca in the first frames of `nnMain` (Hollow Knight: Silksong, Unity 6000.0.50f1: `bt: sdk+0x514580 main+0x1296c64 …`). → [History reads fill every requested entry](../reference/services.md#history-reads-fill-every-requested-entry)
- the game never reads the controller (the title's "Press L+R" never sees a press; no `GetNpadState` call at all). → [Npad style set update event](../reference/services.md#npad-style-set-update-event)
- motion moves never happen; shaking does nothing (Super Mario Odyssey: cap throws by shaking). → [Six-axis sensors](../reference/services.md#six-axis-sensors)
- SDK 20 calls that reach a service; `nfp`'s `AttachActivateEvent` / `AttachDeactivateEvent` crashed in the SDK at `sdk+0x3f2a78`. → [SDK 20 six-axis sensor and amiibo (`nfp`) calls](../reference/services.md#sdk-20-six-axis-sensor-and-amiibo-nfp-calls)
- abort in `nn::sm::Initialize` under `nn::hid::VibrationNode::Update`. → [Vibration values flushed by the SDK's vibration graph](../reference/services.md#vibration-values-flushed-by-the-sdks-vibration-graph)
- `DM_RUMBLE_LOG=1` shows the game's startup handle request answered with none, then every vibration value sent to handle 0 and reaching no output for the whole session, although a controller with haptics (a DualSense on the Mac) is connected. A game that rumbles would stay silent. → [Vibration handles before a controller is reported](../reference/services.md#vibration-handles-before-a-controller-is-reported)
- taps in handheld mode do nothing, though the game reads the touch screen (the title's PRESS ANY BUTTON, the menus' cards). → [Touch gestures recognized from the touch points](../reference/services.md#touch-gestures-recognized-from-the-touch-points)
- the first boot aborted in `hid::GetMouseState` (the SDK's mouse resource was never initialized). → [Mouse, keyboard and key code maps](../reference/services.md#mouse-keyboard-and-key-code-maps)
- the first boot crashed in `hid::detail::SetPalmaBoostMode`, a null read at `sdk+0x238eb0` (the hid service never opened). → [Poké Ball Plus (Palma)](../reference/services.md#poké-ball-plus-palma)
- undefined `irsensor` imports found from the import list (Listing a game's unhooked imports before they are met). → [IR camera reported unconnected](../reference/services.md#ir-camera-reported-unconnected)
- null read in `sdk` under `nn::applet::CreateLibraryApplet` (Engage: title menu → DLC → `nn::ec::ShowShopAddOnContentList`); `Show…` overloads found in the imports before they were met. → [System applets opened by `Show…` calls](../reference/services.md#system-applets-opened-by-show-calls)
- the sound stutters and the input box lags while the player types a name (Octopath Traveler 0 on an iPhone: one 4.7 s frame, 5,035 wakeups a second instead of about 1,800, and no audio underruns). → [The software keyboard blocks only its caller](../reference/services.md#the-software-keyboard-blocks-only-its-caller)
- null read in `applet::CreateLibraryApplet` under `swkbd::InlineKeyboard::Initialize` (3D World, entering the save select after the character select). → [The inline keyboard as a resident library applet](../reference/services.md#the-inline-keyboard-as-a-resident-library-applet)
- texture creation returns null right after the inline keyboard's `Initialize`, then a null read at `main+0x7713044`. → [Inline keyboard window size, setters and callbacks](../reference/services.md#inline-keyboard-window-size-setters-and-callbacks)
- the hunter's name box stays empty, then stays open with the name in it (Monster Hunter Rise, character creation). → [Inline keyboard text callbacks and `Calc` states](../reference/services.md#inline-keyboard-text-callbacks-and-calc-states)
- `CRASH sig=10` at a heap address, called from `main+0x6bca160` right after the name was entered (Monster Hunter Rise); crash in `lmem::AllocateFromExpHeap` under `ngc::ProfanityFilter::MaskProfanityWordsInText` right after the character name is entered (DARK SOULS: REMASTERED); filter methods among the undefined imports with no hook, found from the import list before they were met (The Great Ace Attorney Chronicles). → [`nn::ngc::ProfanityFilter` vtable and by-name overloads](../reference/services.md#nnngcprofanityfilter-vtable-and-by-name-overloads)
- SIGSEGV in `vi::CreateLayer(Layer**, Display*, int, int)` (`sdk+0x3f9bc4`, from SDL3's Switch video driver at `main+0x239304`). → [`vi::CreateLayer` with the layer's size](../reference/services.md#vicreatelayer-with-the-layers-size)
- SIGSEGV in `vi::SetLayerCrop`. → [vi layer and display calls without vi service objects](../reference/services.md#vi-layer-and-display-calls-without-vi-service-objects)
- SIGSEGV in `android::Surface::getQueuedFrameNumber` under `nn::vi::GetLatestFrameNumber`. → [Layer frame numbers](../reference/services.md#layer-frame-numbers)
- SIGSEGV in `vi::GetDefaultDisplayPanelIdentifier` (`main+0xa9a4`, before the window). → [Default display panel identifier](../reference/services.md#default-display-panel-identifier)
- the first boot crashed in `oe::DisableAlbumImageTakenNotification`: a null read at `sdk+0x338070`, the first call in `nnMain` (`main+0x6b188c`); other `oe` calls that reach am, found in the imports before they were met. → [oe calls answered without an applet proxy](../reference/services.md#oe-calls-answered-without-an-applet-proxy)
- abort in `nn::sm::Initialize` under `nn::oe::FinishStartupLogo`, right after the first frames. → [The startup logo](../reference/services.md#the-startup-logo)
- null read in `oe::InitializeCopyrightFrameBuffer`, right after the window setup. → [Copyright frame buffer overlay](../reference/services.md#copyright-frame-buffer-overlay)
- SDK 20 calls that reach a service, each one boot; SDK 20's `OpenAudioRenderer` aborts on an ARUID of 0. → [Applet resource user ID, launch parameters and VR mode](../reference/services.md#applet-resource-user-id-launch-parameters-and-vr-mode)
- a null read in `sdk+0x35258` (apm's session) in `oe::IsCpuOverclockEnabled`, the first call in `nnMain`; null read at `sdk+0x362b8` (`apm::SetCpuOverclockEnabled`) in the first calls of `nnMain` (`main+0x2e1e4c`). → [CPU overclock calls without an apm session](../reference/services.md#cpu-overclock-calls-without-an-apm-session)
- the game freezes after switching apps and back, picture still, sound on; the main loop waits in its pause handshake (`main+0x5d10d4` / `main+0x5cea68`). Mac repro `DM_OE_SCRIPT=bg=1@20,bg=0@25`. → [Focus handling mode decides whether focus changes are notified](../reference/services.md#focus-handling-mode-decides-whether-focus-changes-are-notified)
- abort in `sm::Initialize` under `capsrv::InitializeForApplication` (`album::Initialize`); calls that reach the album service, found in the imports before they were met. → [Album calls fail with no album](../reference/services.md#album-calls-fail-with-no-album)
- a null read at `sdk+0x336ccc` in `pdm::QueryApplicationPlayStatistics` (Pokémon Sword, the second boot); undefined `nn::account::` / `nn::friends::` imports with no hook, found from the import list (Listing a game's unhooked imports before they are met) before they were met. → [Account, friends, play data and Nintendo Account calls](../reference/services.md#account-friends-play-data-and-nintendo-account-calls)
- `[RED] sf: the game connects to service mii:e … mii:u itself`, then an abort. → [Mii database answered by the host](../reference/services.md#mii-database-answered-by-the-host)
- the abort with no message (`SVC 0x15` / `0x1f` / `0x21` placeholders, then `Break` with `sm::Finalize` under `ShopServiceAccessServer::Proxy::Initialize`) from `ec::InitializeForShopServiceAccessors`, called from Unreal's `FOnlineSubsystemSwitch::Init` at the start of `nnMain`. → [Shop service accessors](../reference/services.md#shop-service-accessors)
- abort in `nn::sm::Initialize` under `nn::pctl::IsFreeCommunicationAvailable` (Engage, entering its first battle map). → [Parental controls and free communication](../reference/services.md#parental-controls-and-free-communication)
- play report calls met entering the save select (3D World); undefined `nn::ldn::` / `nn::socket::` imports with no hook, found from the import list before they were met (Big Brain Academy). → [Network interface, LDN, socket and play report calls](../reference/services.md#network-interface-ldn-socket-and-play-report-calls)
- the boot sits at a black loading screen for good, CPU nearly idle, every thread waiting, about 1 boot in 6 (3 in 4 with four Mac hosts at once); the title movie is never opened, and the save files are never probed. → [Network requests stay on hold before they settle](../reference/services.md#network-requests-stay-on-hold-before-they-settle)
- one thread at 100% CPU from boot, with one SVC in 99 s (`NexusRevolution Socket`, `main+0x92c7c4`, the game's network thread). → [Socket `Poll` and `Select` with nothing to wait on](../reference/services.md#socket-poll-and-select-with-nothing-to-wait-on)
- the first comparison in `nnMain` aborted in `sm`. → [Language codes](../reference/services.md#language-codes)
- abort in `sm::Initialize` under `nn::settings::GetAvailableLanguageCodes` (early in `nnMain`, `main+0x327888`); abort in `sm::Initialize` under `nn::settings::GetAvailableLanguageCodeCount()` (`main+0x117590`). → [Available language codes and their count](../reference/services.md#available-language-codes-and-their-count)
- the font engine runs on garbage; crash after the shared fonts load, looking up the "?" glyph (`main+0x6c73c0`, a font cache lookup returning null), with SDK 10's `ScalableFontEngine::LoadFont` failing with error 403 and `SetFont` with 301 on both stand-in fonts; or Japanese, Korean or Chinese text draws nothing in a Unity game while Latin text is fine (Patrick's Parabox's language menu showed three blank lines). → [Shared font address: BFTTF header or bare TTF](../reference/services.md#shared-font-address-bfttf-header-or-bare-ttf)
- abort in `nn::sm::Initialize` under `nn::pl::sharedresource::GetPlatformSharedResourceManager` (first thing in `nnMain`). → [Shared fonts requested all at once](../reference/services.md#shared-fonts-requested-all-at-once)
- controller-button icons in text show as `?`. → [Nintendo-extension glyphs for button icons](../reference/services.md#nintendo-extension-glyphs-for-button-icons)
- on a phone, `GetSharedFontLoadState` would report "not loaded". → [Shared fonts on iOS](../reference/services.md#shared-fonts-on-ios)
- SDK calls that reach the time service, each aborting in `sm::Initialize` (or found in the imports before they were met). → [Steady clock, clock snapshots and user clocks](../reference/services.md#steady-clock-clock-snapshots-and-user-clocks)
- `std::terminate` (`Break` from `sdk+0x5bfa48`) at the first real-time read (right after the first-boot dialog, `main+0x3f3f68` → `system_clock::now()`). → [`clock_gettime(CLOCK_REALTIME)` through the time source pointer](../reference/services.md#clock_gettimeclock_realtime-through-the-time-source-pointer)
- after switching apps and back, one guest thread at 100% in a tight loop (`main+0x9abd0`, `x10 = 0`); the game freezes, picture still, sound on. Mac repro `DM_OE_SCRIPT=bg=1@20,bg=0@25`. → [Guest clock reads wait while the app is in the background](../reference/services.md#guest-clock-reads-wait-while-the-app-is-in-the-background)
- abort in `sm::Initialize` under `nn::crypto::GenerateCryptographicallyRandomBytes` (Unicorn Overlord: `std::random_device` → the `sdk`'s own `getentropy` → `InitializeCsrng`; Z-A: the first call in `nnMain`, `main+0x1734b4`). → [Cryptographically random bytes](../reference/services.md#cryptographically-random-bytes)
- relocation repeatedly scans all HLE and forced-takeover entries, and named-stub reuse becomes quadratic as more imports are missing. → [Host symbol indexes avoid repeated name scans](../reference/services.md#host-symbol-indexes-avoid-repeated-name-scans)
- a library's `free` rejects a pointer (`CentralHeap::Free` → `NotNMallocPtrError`). → [Global symbol resolution in load order](../reference/services.md#global-symbol-resolution-in-load-order)
- a weakly imported function the game calls although nothing defines it: an `UNIMPL` line, then an abort. → [Undefined weak imports bind to 0](../reference/services.md#undefined-weak-imports-bind-to-0)
- crash in `nn::ro::InitializeWithPortName`. → [`nn::ro` and its port](../reference/services.md#nnro-and-its-port)
- the frame loop runs, but the game waits for code it loads itself (`ro::RegisterModuleInfo` / `ro::GetBufferSize` red lines; `main` imports 1,045 `lua2cpp::create_agent_*` functions, global, that no ExeFS module defines, bound to stubs at start). → [Loading NROs with `ro::LoadModule`](../reference/services.md#loading-nros-with-roloadmodule)
- `[EOS] Failed to create platform` (the game plays offline); `refused …: an online SDK (Epic Online Services), not loaded`; `refused an NRR that registers only online SDKs (1 hashes)`. → [Online SDKs in NROs are never loaded](../reference/services.md#online-sdks-in-nros-are-never-loaded)
- `main` imports EGL (SDL3's GL support) and `vkGetInstanceProcAddr` (its Vulkan support), but the game renders with NVN (`FNA3D_Driver_NVN.cpp`). → [GPU driver modules that are never loaded](../reference/services.md#gpu-driver-modules-that-are-never-loaded)
- `UNIMPL _ZN5movie12SetAllocatorEPFPvmmS0_EPFvS0_S0_EPFS0_S0_mS0_ES0_`, `UNIMPL glslcInitialize`, then `UNIMPL _ZN5movie9ExtractorC1ENS_13ContainerTypeE` and a crash reading address 0x18 in an NRO (`pc=nro18+0x97f4`) as the first movie starts. → [Modules only the NROs import from](../reference/services.md#modules-only-the-nros-import-from)
- `[RED] ro::LookupModuleSymbol BuiltDebug: not defined in that module` once at boot; nothing goes wrong after it. → [`ro::LookupModuleSymbol` for a name the module does not define](../reference/services.md#rolookupmodulesymbol-for-a-name-the-module-does-not-define)
- harmless on the build it was written for, silent memory corruption on any other. → [Code inherited from another title at fixed addresses](../reference/services.md#code-inherited-from-another-title-at-fixed-addresses)

## Movies

- abort in NVIDIA's video path (`NvRmChannelOpen` → `NvOsDrvOpen`). → [The SDK's hardware decoder opens nvdrv](../reference/movies.md#the-sdks-hardware-decoder-opens-nvdrv)
- the game waits forever at a movie (Engage's 94 s opening `S01F.webm`; frames keep presenting, nothing happens). → [`movie::Decoder` taken over as a MediaCodec-style protocol](../reference/movies.md#moviedecoder-taken-over-as-a-mediacodec-style-protocol)
- a movie in grey with vertical bands of colour, its luma sharp; or a read far outside guest memory at `main+0x344f74` on the first movie picture (CRI Sofdec2's NV12 → RGB conversion). → [Output format keys (`md_format`)](../reference/movies.md#output-format-keys-md_format)
- a call through a null pointer in the host's `movie::Decoder::Configure` right after `nnMain` starts the logos. → [SDK 4's `movie::Decoder` constructor without a priority](../reference/movies.md#sdk-4s-moviedecoder-constructor-without-a-priority)
- the first deferred signal crashed in `InternalCriticalSectionImplByHorizon::Enter` (DRAGON QUEST XI S). → [Client events read through the registered pointer](../reference/movies.md#client-events-read-through-the-registered-pointer)
- the process dies when an activity starts, 2 runs in 5, with no `CRASH` line: the run ends with exit 137 (SIGKILL), and `~/Library/Logs/DiagnosticReports/dmhost-*.ips` has `EXC_BREAKPOINT` in `_os_unfair_lock_corruption_abort` ← `pthread_mutex_destroy` ← `md_free` (the movie decoder's destructor). → [Input indices returned by a flush while a client holds them](../reference/movies.md#input-indices-returned-by-a-flush-while-a-client-holds-them)
- when the prologue movie was skipped, 2.25 GB were mapped within seconds, past the application pool, and the game crashed in its allocator (DRAGON QUEST XI S). → [End of stream is the last input until `Flush` or `Stop`](../reference/movies.md#end-of-stream-is-the-last-input-until-flush-or-stop)
- decoding the end-of-stream packet gave VideoToolbox −12909 and AudioToolbox −50. → [End-of-stream packets with no data, and deleted decoders](../reference/movies.md#end-of-stream-packets-with-no-data-and-deleted-decoders)
- the game never leaves a movie that has played to its end; the last picture stays on screen. → [H.264 drain at the end of a stream goes on with released slots](../reference/movies.md#h264-drain-at-the-end-of-a-stream-goes-on-with-released-slots)
- the opening movie never starts, in about half the boots (DRAGON QUEST XI S: a black screen and no sound from boot on). → [Audio decoders keep more outputs than a pre-decoding player fills](../reference/movies.md#audio-decoders-keep-more-outputs-than-a-pre-decoding-player-fills)
- a movie stays black after its first picture, the sound never starts, and the game keeps presenting frames. → [Audio output slots for players that hold every output](../reference/movies.md#audio-output-slots-for-players-that-hold-every-output)
- a movie shows as a black screen with the loading icon, one picture every few seconds, while its sound decoder keeps up. → [Video output slots: how far the extractor gets ahead](../reference/movies.md#video-output-slots-how-far-the-extractor-gets-ahead)
- a crash in the game's heap free (`sead::ExpHeap`) on a movie thread, a second into the first movie, at the same address every boot (`pc=main+0x42f980`, a free-list unlink through a link of 0x3f, `addr=0x47`). → [AAC decoders offer at most 32 outputs](../reference/movies.md#aac-decoders-offer-at-most-32-outputs)
- the movie then froze on its first second, its sound decoder full and the game taking no more audio. → [AAC output buffer size is one frame](../reference/movies.md#aac-output-buffer-size-is-one-frame)
- `FATAL movie: missing SDK symbol _ZNK5movie6Buffer10GetNvnSyncEv` at the first frame of the native-texture movie (H.264 into the game's RGBA texture, as in Monster Hunter Rise). → [SDK 4's `movie::Buffer` has no sync object](../reference/movies.md#sdk-4s-moviebuffer-has-no-sync-object)
- a native-texture movie shows as a strip of small grey copies at the top of the screen. → [Parameter sets in `Configure` made the H.264 decoder without RGBA](../reference/movies.md#parameter-sets-in-configure-made-the-h264-decoder-without-rgba)
- looping movie previews flash black at the end of every loop. → [Last picture kept across a flush and at end of stream](../reference/movies.md#last-picture-kept-across-a-flush-and-at-end-of-stream)
- the game crashed on a null right after the failed open. → [`movie::Extractor` runs natively](../reference/movies.md#movieextractor-runs-natively)
- VP8 WebM movies play black; `movie::Decoder` is created with decoder type 2. → [VP8 uses the same libvpx worker and output paths](../reference/movies.md#vp8-uses-the-same-libvpx-worker-and-output-paths)

## Audio

- abort with Result 0x499 in `audio::GetAudioRendererWorkBufferSize`. → [SDK 8's longer `AudioRendererParameter`](../reference/audio.md#sdk-8s-longer-audiorendererparameter)
- the game is silent; only the game's updates render (catch-up frames that nothing plays). The log has `audren: OpenAudioRenderer (no event)` and no `render thread started`. → [A renderer opened without an event](../reference/audio.md#a-renderer-opened-without-an-event)
- `[RED] audren: a second renderer` right after the first open, with the same work buffer and "original device 1 mode 1". → [The SDK's open with an event calls the open without one (`t_in_open`)](../reference/audio.md#the-sdks-open-with-an-event-calls-the-open-without-one-t_in_open)
- the frame loop stops for good as a level loads while audio keeps rendering. The main thread waits in `os::WaitSystemEvent` under `CAudioMemoryPool::Shutdown`, and a sound thread of higher priority waits on the same condition variable. → [The renderer event as the service gives it: a kernel event](../reference/audio.md#the-renderer-event-as-the-service-gives-it-a-kernel-event)
- none of its own; command generation races the game's `Update` on SDKs whose lock is not at SDK 16's offset. → [The renderer's update lock (`update_lock`)](../reference/audio.md#the-renderers-update-lock-update_lock)
- `FATAL audren: missing SDK symbol _ZN2nn2os12SdkMutexType4LockEv` right after the renderer's render thread starts. → [No `SdkMutexType` in SDK 3](../reference/audio.md#no-sdkmutextype-in-sdk-3)
- `CommandListProcessor::Process` crashes now and then (SIGSEGV under `render_main`, once at 60 s and once at 134 s in the shrine); every `RequestUpdate` renders a catch-up frame. → [The render thread's route through the public `ExecuteAudioRendererRendering` (SDK 20)](../reference/audio.md#the-render-threads-route-through-the-public-executeaudiorendererrendering-sdk-20)
- SIGSEGV at address 0x18 in `UpsamplerManager::Allocate` on the render thread. → [A renderer below 48 kHz with no upsampler on the CPU](../reference/audio.md#a-renderer-below-48-khz-with-no-upsampler-on-the-cpu)
- the main thread spins at start-up in a resource wait (a `YieldThread` loop, no crash), right after `OpenAudioRenderer`. → [A sound engine's heap too small for its renderer and players](../reference/audio.md#a-sound-engines-heap-too-small-for-its-renderer-and-players)
- the CPU processor drops the final mix. → [The final mix is taken from the DeviceSink's mix buffers](../reference/audio.md#the-final-mix-is-taken-from-the-devicesinks-mix-buffers)
- no sound: `[RED] audren: no DeviceSink (ID 0x10) in the command list, 0 commands of 0x148 bytes`. → [SDK 4: DeviceSink is command 0xf of 0x130 bytes](../reference/audio.md#sdk-4-devicesink-is-command-0xf-of-0x130-bytes)
- no sound; red `audren: command 1 in the command list is malformed (magic 0 size 0)`. → [SDK 6: the DSP command header layout](../reference/audio.md#sdk-6-the-dsp-command-header-layout)
- no music and no sound effects, only the movies' sound (the log repeats `audren: first-frame commands …` every frame and never prints `DeviceSink inputs`). → [SDK 8: command IDs numbered differently](../reference/audio.md#sdk-8-command-ids-numbered-differently)
- no sound; red `audren: command 0 in the command list is malformed (first word 0x181901 size 0)`. → [SDK 21 DSP command header without a magic](../reference/audio.md#sdk-21-dsp-command-header-without-a-magic)
- FMOD waits for buffer release after stopping an AudioOut, hanging the game during a scene transition. → [Stopping an AudioOut releases its pending buffers](../reference/audio.md#stopping-an-audioout-releases-its-pending-buffers)
- crackling on iOS only. → [RemoteIO's default I/O buffer duration](../reference/audio.md#remoteios-default-io-buffer-duration)
- clicks and dropouts on the Mac, heard as clipping; the log's `audio #N device callbacks` lines show hundreds of underruns per 2000 callbacks. Closing an output can also log `[RED] audio device buffer: ... (status 560947818)` (`!obj`). → [The Mac's default I/O buffer](../reference/audio.md#the-macs-default-io-buffer)
- sound stays silent after Siri, an alarm, a call or another app's audio; a game whose audio thread waits for its buffers back (Wwise's poll-only output, FMOD) then waits forever. → [Interruptions that stop RemoteIO callbacks](../reference/audio.md#interruptions-that-stop-remoteio-callbacks)
- combined numbers mislead: one fully fed output plus one fed by nobody look like "every other callback underruns, 2.0 blocks queued". → [Several outputs at once (`audio #N`)](../reference/audio.md#several-outputs-at-once-audio-n)
- a null read at `sdk+0x1f2314` as the first movie starts (the title menu's background, right after the first press), in `nn::audio::SetAudioOutVolume`, called from `main+0x1c4fbc`. → [AudioOut volume kept per output](../reference/audio.md#audioout-volume-kept-per-output)
- a null read in `audio::GetAudioOutBufferCount` on Wwise's sink wakeup thread (`sdk+0x1e7ed0`, from `main+0x30faae8`). → [AudioOut buffer count from the host queue](../reference/audio.md#audioout-buffer-count-from-the-host-queue)
- an abort in `sm::Initialize` under `audio::GetAudioDeviceOutputVolume` (the game thread, `main+0xee8edc`). → [Audio device output volume and names](../reference/audio.md#audio-device-output-volume-and-names)
- SDL3's audio driver lists the input devices (AudioIn) when its audio starts. → [No audio input devices](../reference/audio.md#no-audio-input-devices)
- an abort in `sm::Initialize` under the hardware Opus decoder's C interface; for the multi-stream one, under `nn::codec::GetHardwareOpusMultiStreamDecoderWorkBufferSize(int, int, int, int, int)` (at `nnMain`, CRI's Opus streams). An abort in `sf::hipc::InitializeHipcServiceResolution` under `codec::GetHardwareOpusDecoderWorkBufferSize(int, int)` (`main+0x31f8e8`, early in `nnMain`). A game that builds `HardwareOpusMultiStreamDecoder` with the imported constructor and then calls it through its vtable. → [Hardware Opus decoders built on the SDK's software decoders](../reference/audio.md#hardware-opus-decoders-built-on-the-sdks-software-decoders)
- the light limiter crashed on a null state pointer (`ApplyLightLimiterEffect`, `sdk+0x228494`). → [At least one rendered frame between two updates](../reference/audio.md#at-least-one-rendered-frame-between-two-updates)
- the sound runs about 50 times faster than the output; the loop runs 11,000 updates a second on one core. → [A sound driver that never waits on the renderer event](../reference/audio.md#a-sound-driver-that-never-waits-on-the-renderer-event)

## Frame rate

- a 30 fps game to run at 60; after the floor was lowered, slow motion on a GPU-bound device (GitHub issue #9). → [sead's dynamic present interval, `ksys::VFR` and the host's frame step](../reference/frame-rate.md#seads-dynamic-present-interval-ksysvfr-and-the-hosts-frame-step)
- on an iPhone, a game with the frame step at 60 fps drops a frame in most windows after a few minutes, and its GPU time per frame roughly doubles to triples (17-26 ms for the same scenes). → [A thermally serious iPhone holds 30 fps](../reference/frame-rate.md#a-thermally-serious-iphone-holds-30-fps)
- after a 30 fps cap ends (a prerendered movie, the thermal cap), a GPU-bound game stays at 30 fps in a scene that held 60 before the cap; the log shows `frame step cap 30 → 60 fps` and a few frames later `frame step: hold 1 → 2 vsyncs at present … (3 late frames; …)`, with no probe after it. → [The frame step after a 30 fps cap ends](../reference/frame-rate.md#the-frame-step-after-a-30-fps-cap-ends)
- slow motion when the GPU is the bottleneck: a game's interval controller that times the GPU never steps up (GitHub issue #9). → [GPU timestamps per submission segment](../reference/frame-rate.md#gpu-timestamps-per-submission-segment)
- GPU time reads 32 times too small when a game converts raw NVN counter timestamps itself. → [Raw NVN timestamp units](../reference/frame-rate.md#raw-nvn-timestamp-units)
- menus reach 60 fps with `present_interval display`, but entering gameplay returns to 30 fps despite spare GPU time. → [Unity's integer target frame rate](../reference/frame-rate.md#unitys-integer-target-frame-rate)
- the game presents at interval 1, yet every frame takes exactly 33.3 ms of "frame work"; after only the limiter was raised, everything ran twice as fast on the iPhone. → [A render-thread limiter with a constant and a fixed time step](../reference/frame-rate.md#a-render-thread-limiter-with-a-constant-and-a-fixed-time-step)
- 55 fps with every frame 18.2 ms, the main thread asleep most of the time; every 11th frame stays on screen two vsyncs. → [A frame-end wait polled in 2 ms sleeps](../reference/frame-rate.md#a-frame-end-wait-polled-in-2-ms-sleeps)
- the app is active and the game keeps running, but the picture freezes while display-link callbacks stop; the log repeatedly drops queued frames. → [Present thread rescues a silent display link](../reference/frame-rate.md#present-thread-rescues-a-silent-display-link)
- with the display link driving presents, a presented frame comes out black when three presents are on the GPU at once, or two after a dropped frame; on an M6 the same reuse also logs `[RED] display command buffer error` with `kIOGPUCommandBufferCallbackErrorPageFault`. → [A present command allocator is reused only after its own present completes](../reference/frame-rate.md#a-present-command-allocator-is-reused-only-after-its-own-present-completes)
- "sometimes the speed increases when jumping" (Mario 1.2.1 on the iPhone): in `display` mode interval-2 frames were shown for 16.7 ms and the game visibly jumped ahead. "When pressing B, Link's move pace is speeding up" (Breath of the Wild on the iPhone); `old frames dropped by merging`. → [Frames of a dynamic present interval held on screen and at the acquire](../reference/frame-rate.md#frames-of-a-dynamic-present-interval-held-on-screen-and-at-the-acquire)
- frames miss the screen while the GPU stays at its lowest clock (444 MHz on an M2 Max); more work (a higher render scale) only makes the frames slower. → [Present snapshots: the game's swapchain texture free at once](../reference/frame-rate.md#present-snapshots-the-games-swapchain-texture-free-at-once)
- a steady game whose frame-rate counter wanders between 50 and 60 on the iPhone only; the `display link up to tick` lines show about as many empty ticks as frames dropped by merging: frames arrive two in one tick and none in the next. → [Vulkan acquire and vsync event follow the display link](../reference/frame-rate.md#vulkan-acquire-and-vsync-event-follow-the-display-link)
- asked for 60 Hz, the system fires the display link on every third refresh of a 165 Hz screen, 55 Hz, so games paced by it ran at 55 fps (27.5 at 30). → [Virtual 60 Hz ticks on screens that are not a multiple of 60](../reference/frame-rate.md#virtual-60-hz-ticks-on-screens-that-are-not-a-multiple-of-60)
- virtual ticks keep the average, but a frame still stays up two or three refreshes in turn (13.9 / 20.8 ms at 144 Hz), and Apple's HUD showed the frame interval jumping between them. → [Fullscreen switches the screen to a rate the frame rate divides](../reference/frame-rate.md#fullscreen-switches-the-screen-to-a-rate-the-frame-rate-divides)
- autorelease work takes a measurable share of replay time, with temporary arena-buffer ownership traffic a few times per draw. → [Arena buffer ownership on allocation](../reference/frame-rate.md#arena-buffer-ownership-on-allocation)
- the submit thread waits on the texture / sampler registry lock while a lower-priority registration thread is preempted holding it. → [Registry lock priority inheritance](../reference/frame-rate.md#registry-lock-priority-inheritance)
- in a replay profile, `_platform_memcmp` is most of the time spent in serial lookups (`tex_mtl` through `g_by_serial`). → [Hash-table lookups of 8-byte keys](../reference/frame-rate.md#hash-table-lookups-of-8-byte-keys)
- the GPU sits idle each frame while the host translates the submission (a game that does not submit frame N+1 until frame N's GPU work is done). → [Submissions handed to the GPU in segments](../reference/frame-rate.md#submissions-handed-to-the-gpu-in-segments)
- the submit thread's CPU samples dominated by `mtl_addr` / `mtl_gpu_addr` (vertex buffers in `draw`, uniform buffers in `encode_args`). → [Address to memory pool lookups by binary search](../reference/frame-rate.md#address-to-memory-pool-lookups-by-binary-search)
- stalls of 30–60 ms about once a second, at 30 fps and at 60 (99th percentile 63–127 ms); the main thread waits 20–34 ms for the render thread once a second. → [Time-constraint computation declared below the thread's peaks](../reference/frame-rate.md#time-constraint-computation-declared-below-the-threads-peaks)

## NVN objects

- heap corruption; a stack smash where a function returned to `0x100000000`; a crash in SHA-256 on the code address 0x16300. → [Host records must fit the game's SDK object sizes](../reference/nvn-objects.md#host-records-must-fit-the-games-sdk-object-sizes)
- out-of-range vertices, NaN, a black band and flicker; seen on the iPhone, while Mac runs of the same scene looked clean. → [Inlined SDK code writes into `NVNcommandBuffer` +0x10](../reference/nvn-objects.md#inlined-sdk-code-writes-into-nvncommandbuffer-0x10)
- sprites broke apart in some runs only, depending on the allocation order; buffers overlapped. → [Sizes the hardware never reports as 0 (ZCull save area)](../reference/nvn-objects.md#sizes-the-hardware-never-reports-as-0-zcull-save-area)
- a null write as soon as the main thread starts recording a command buffer (13 Sentinels: a constructor at `main+0x2fa9a0` runs on `this = 0` when the prologue enters its first battle). → [Heaps cut from a pool at alignment relative to its GPU address](../reference/nvn-objects.md#heaps-cut-from-a-pool-at-alignment-relative-to-its-gpu-address)
- `[RED] memory pool … created at retry N`. → [`newBufferWithBytesNoCopy` retried under memory pressure](../reference/nvn-objects.md#newbufferwithbytesnocopy-retried-under-memory-pressure)
- a buffer is created with a null pool right after a scene change. → [Virtual memory pools mapped onto one physical pool](../reference/nvn-objects.md#virtual-memory-pools-mapped-onto-one-physical-pool)
- `[RED] MapVirtual: non-contiguous mapping (true sparse) not implemented`. → [Sparse virtual pools built from separate physical pools](../reference/nvn-objects.md#sparse-virtual-pools-built-from-separate-physical-pools)
- `[RED] MapVirtual: non-contiguous mapping (true sparse) not implemented`, on small virtual pools; streamed textures black or missing (OCTOPATH TRAVELER's village ground and plants). → [Virtual pools of one texture each, mapped before and after the texture](../reference/nvn-objects.md#virtual-pools-of-one-texture-each-mapped-before-and-after-the-texture)
- `[RED] NVN unimplemented function called: nvnTextureBuilderGetSparseTileLayout`, then an out-of-memory abort in Unreal's allocator (`Failed to allocate 1879113728 bytes from Standard Allocator`, on `DM_DBG=1`). → [The sparse tile layout of a texture](../reference/nvn-objects.md#the-sparse-tile-layout-of-a-texture)
- `CRASH sig=10` in `memmove` from `pkg_upload` → `nvn_deswizzle`, at an address 32 GB into a sparse virtual pool; textures with unaliased tails came out magenta. → [Textures read through a 4 KB page table of a sparse pool](../reference/nvn-objects.md#textures-read-through-a-4-kb-page-table-of-a-sparse-pool)
- GPU memory grows with every scene change (Engage's idle title demo reached 5.4 GB of GPU memory and 3.6 GB resident in 850 s). → [Finalized pools kept alive by residency and the sharing table](../reference/nvn-objects.md#finalized-pools-kept-alive-by-residency-and-the-sharing-table)
- the memory line's `freed but alive` count only grows, while no host table holds those buffers; "GPU allocated" is far above resident memory (Ghost Trick: Phantom Detective, 125 to 146 buffers and 6.6 to 8.7 GB of GPU allocations against 2.2 GB resident). → [Finalized pool buffers kept by a guest thread's autorelease pool](../reference/nvn-objects.md#finalized-pool-buffers-kept-by-a-guest-threads-autorelease-pool)
- the serial table grows by about 10 entries a frame (276,000 after 25,000 frames). → [Dead texture serials kept in a ghost table](../reference/nvn-objects.md#dead-texture-serials-kept-in-a-ghost-table)
- `FATAL NVN command memory: the game's pool is empty…`. → [Host-lent command memory segments](../reference/nvn-objects.md#host-lent-command-memory-segments)
- frames stop after about 15 s; a game thread spins in its command-memory callback (a ring allocator at `main+0x9cc120` waiting for fences that have all signalled). → [What `GetCommandMemoryUsed` counts](../reference/nvn-objects.md#what-getcommandmemoryused-counts)
- `CRASH sig=10` in `mtl_exec` after minutes of play, the fault address equal to `x19` and shaped like `0x1000000003`. → [Prerecorded lists in slots of their measured size](../reference/nvn-objects.md#prerecorded-lists-in-slots-of-their-measured-size)
- the title showed one stretched 64×64 icon over the 3D scene, a new game a white screen; post-process passes with stale texture handles; `[RED] bind record … overwritten after recording`. → [Recorded commands patched in place by the game (`OP_BIND_TEX1`)](../reference/nvn-objects.md#recorded-commands-patched-in-place-by-the-game-op_bind_tex1)
- `nvnCommandBufferFenceSync` unimplemented, every `SyncWait` timed out at once. → [Fence syncs recorded in command buffers](../reference/nvn-objects.md#fence-syncs-recorded-in-command-buffers)
- `FATAL submit re-entered` in the first frames. → [Submissions from two queues on two threads](../reference/nvn-objects.md#submissions-from-two-queues-on-two-threads)
- frames stop, no crash, the main thread sits in `nvnSyncWait(sync, -1)`, and the watchdog's wait-state line shows the main fence one short (`main fence submitted N / completed N-1`). → [A GPU command buffer that never completes](../reference/nvn-objects.md#a-gpu-command-buffer-that-never-completes)
- the frame's blocking SyncWait on its newest fence wakes about 0.26–0.29 ms after the GPU end (M2 Max; the wait ledger, `DM_NVN_WAITS=1`), on the critical path of every frame. → [The game's SyncWait wakes on the GPU's own signal of its fence](../reference/nvn-objects.md#the-games-syncwait-wakes-on-the-gpus-own-signal-of-its-fence)
- loading screens many times slower on the iPhone than on the Mac (Three Houses' first loading screen 78 s on the iPhone, 5 s on the Mac). → [`nvnQueueFinish` waits for the GPU, not the display](../reference/nvn-objects.md#nvnqueuefinish-waits-for-the-gpu-not-the-display)
- CPU texture uploads spend time recalculating block-linear addresses and calling variable-length `memcpy` for every 16-byte segment. → [CPU deswizzle copies use slice and row offsets](../reference/nvn-objects.md#cpu-deswizzle-copies-use-slice-and-row-offsets)
- driver comparisons report the wrong block dimensions for packaged 2D / 3D textures, or too little storage for linear block-compressed textures (64x64 BC1 with stride 128: 2048 bytes instead of 8192). → [Packaged texture block dimensions and linear storage rows](../reference/nvn-objects.md#packaged-texture-block-dimensions-and-linear-storage-rows)
- menus and dialogue boxes draw but contain no text, while images and pictogram digits are fine; the sky is black (CPU-written linear colour ramps). → [Linear textures in CPU-visible pools](../reference/nvn-objects.md#linear-textures-in-cpu-visible-pools)
- a trap during graphics initialization in `SetupSurfaceInfoMemoryInside`, asserting `ctx.memorySize <= localmemsetupinfo.memorySize`. → [Linear render-target storage without the LINEAR flag](../reference/nvn-objects.md#linear-render-target-storage-without-the-linear-flag)
- video frames, or a game's built-in default textures, are all zero. → [Textures written with `nvnTextureWriteTexels`](../reference/nvn-objects.md#textures-written-with-nvntexturewritetexels)
- after a few minutes of play the main thread spends whole frames in `WriteTexels` (Metroid Dread's frames stopped at about 175 s). → [`WriteTexels` regions written in place by block-linear address](../reference/nvn-objects.md#writetexels-regions-written-in-place-by-block-linear-address)
- black screen with every geometry right (`DM_NVN_HILITE` shows each sprite and glyph in place); the uniform buffer right (a `CBDUMP`), so every texture read 0. → [A pool's storage at creation is its textures' content](../reference/nvn-objects.md#a-pools-storage-at-creation-is-its-textures-content)
- a texture the game filled with `memcpy` and flushed reads as zeros (BotW's sky brownish grey, the distant haze brown). → [First-use fill of storage the game flushed](../reference/nvn-objects.md#first-use-fill-of-storage-the-game-flushed)
- magenta (ASTC's error colour) where UI images belong: a title logo and menu panels, while the 3D scene and the text draw; `DM_NVN_ZBLOCK=1` reports nothing (the textures are not uploaded on the CPU at all); `DM_NVN_TEXINFO=WxH` shows storage holding data at first use (`non-zero …`) in a pool with flags 0x22 (`CPU_UNCACHED | GPU_CACHED`). → [Storage of a CPU-uncached pool at first use](../reference/nvn-objects.md#storage-of-a-cpu-uncached-pool-at-first-use)
- a movie plays black (Age of Calamity: its intro movie under the "+ Skip" prompt). → [Mapped-range flushes taken as uploads (`tex_flush_upload`)](../reference/nvn-objects.md#mapped-range-flushes-taken-as-uploads-tex_flush_upload)
- magenta surfaces (Metal decodes an all-zero ASTC block as the error colour (1, 0, 1)); a zero BC block decodes black, which looks like missing light; black screen while the UI (or a dialog box) draws in the right places under `HILITE` or in the pass dump; `packaged textures: first uploads 0`. → [CPU writes with no flush, caught by page protection (`tex_dirty_upload`)](../reference/nvn-objects.md#cpu-writes-with-no-flush-caught-by-page-protection-tex_dirty_upload)
- a texture the game builds from CPU-filled textures read back with `nvnTextureReadTexels` comes out zero. → [`ReadTexels` from guest memory and textures written after first use](../reference/nvn-objects.md#readtexels-from-guest-memory-and-textures-written-after-first-use)
- textures that should hold CPU-written data come out magenta (ASTC's error colour) or black. → [Sampled textures in a sparse pool uploaded through the page table](../reference/nvn-objects.md#sampled-textures-in-a-sparse-pool-uploaded-through-the-page-table)
- some textures are re-uploaded every frame (several MB per frame). → [Dirty-page ranges of pools that share a host page](../reference/nvn-objects.md#dirty-page-ranges-of-pools-that-share-a-host-page)
- packaged textures re-uploaded at every use with unchanged content; upload staging and frame times rising. → [Writes beside a packaged texture in a shared host page](../reference/nvn-objects.md#writes-beside-a-packaged-texture-in-a-shared-host-page)
- about one run in four stalled early (around the opening movie or the title), with no log output, not even the time-limit report. → [Dirty-page tracker race and early stalls](../reference/nvn-objects.md#dirty-page-tracker-race-and-early-stalls)
- a CPU-written texture stays stale after later writes; letters can be missing from a glyph cache. → [Dirty-page writes missed during upload](../reference/nvn-objects.md#dirty-page-writes-missed-during-upload)
- device / subsystem setup returns quietly and the next stage never starts. → [Version and capability checks that fail quietly](../reference/nvn-objects.md#version-and-capability-checks-that-fail-quietly)
- a null-pointer crash early in `nnMain`, right after NVN setup should have happened (Super Mario 3D World + Bowser's Fury, `main+0x759e08`: the device singleton `main+0x1a28ea0` is still null). → [The device's API version](../reference/nvn-objects.md#the-devices-api-version)
- null read at `main+0xb8462c` right after the first two textures, called from `main+0x670eb0` (Bayonetta 3), or cleanup crashes at `main+0x9c0d1c` after shader initialization fails (ASTRAL CHAIN). → [Newest GPU code version reported by the driver](../reference/nvn-objects.md#newest-gpu-code-version-reported-by-the-driver)
- a jump to pc=0 right after the NVN bootstrap loader (`lr=main+0x37fe930`, `[RED] NVN address lookup of an unknown name: nvnSetExternalDebuggerEnabledNVX`). → [Extensions fetched by name and called unchecked](../reference/nvn-objects.md#extensions-fetched-by-name-and-called-unchecked)
- SIGBUS in `AGCDeserializedReply`, address in the guest stack region. → [NVN entry points on the big host stack](../reference/nvn-objects.md#nvn-entry-points-on-the-big-host-stack)
- red `NVN unimplemented function called` lines for `nvnColorStateGetBlendEnable`, `nvnBlendStateGetBlendFunc`, `nvnPolygonStateGetCullFace`, `nvnDepthStencilStateGetDepthTestEnable`, `nvnBufferBuilderGetSize`, `nvnTextureBuilderGetWidth`, …. → [State read back through NVN getters](../reference/nvn-objects.md#state-read-back-through-nvn-getters)
- an abort in device setup when `nvnTexturePoolGetSize` / `nvnSamplerPoolGetSize` returned 0. → [Pool size getters, texture address and command memory size](../reference/nvn-objects.md#pool-size-getters-texture-address-and-command-memory-size)
- red stub lines for NVN calls. → [NVN calls that were red stubs](../reference/nvn-objects.md#nvn-calls-that-were-red-stubs)
- `nvnWindowGetPresentInterval`, `nvnCommandBufferSetCopyImageStride` missing. → [SDK 8 window and copy-stride entry points](../reference/nvn-objects.md#sdk-8-window-and-copy-stride-entry-points)

## Rendering

- Metal aborts on a texture descriptor with an absurd size (`height (1869367126) greater than … 16384`). → [Texture objects copied into command records](../reference/rendering.md#texture-objects-copied-into-command-records)
- a decoded movie stays black even though its YUV textures contain the picture; disabling its depth test makes it visible. → [New textures start as zero](../reference/rendering.md#new-textures-start-as-zero)
- glyphs render as white boxes (the font atlas is `(1, 1, 1, R)`). → [Texture swizzle through swizzled Metal views](../reference/rendering.md#texture-swizzle-through-swizzled-metal-views)
- dark boxes and cream cloud rectangles behind HUD prompts, a black stamina wheel and a black System menu background (layout captures). → [`nvnTextureCompare` compares the channel mapping](../reference/rendering.md#nvntexturecompare-compares-the-channel-mapping)
- `newTextureViewWithPixelFormat` takes a large share of the replay thread (45% in Age of Calamity) when a game registers textures into a ring of IDs before every bind. → [Texture views cached by texture and view parameters](../reference/rendering.md#texture-views-cached-by-texture-and-view-parameters)
- daylight scenes washed out to white (every read of a texture returned one fixed value); `texture type mismatch` red lines. → [Compatible views for a mismatched declared texture type](../reference/rendering.md#compatible-views-for-a-mismatched-declared-texture-type)
- a type mismatch when a Metal 1D texture is bound to a shader's `texture2d` argument. → [1D textures as one-row 2D textures](../reference/rendering.md#1d-textures-as-one-row-2d-textures)
- shaders that sample a cube texture as `texturecube_array` get a type mismatch. → [Cube textures held as 6-layer 2D arrays](../reference/rendering.md#cube-textures-held-as-6-layer-2d-arrays)
- an abort in `MTLTextureDescriptor` validation, `arrayLength (510) … greater than the max allowed size (341)`, when the prologue movie ends. → [Cube map arrays count layer-faces](../reference/rendering.md#cube-map-arrays-count-layer-faces)
- an abort in Metal's validation: `newSliceRange.length(1) must be a multiple of (6)`. → [Cube views count their layers in cubes](../reference/rendering.md#cube-views-count-their-layers-in-cubes)
- `texture type mismatch … declares slot 10 as Metal type 5, texture … is type 3` (undefined reads); the later `[RED] texture type mismatch: shader declares a cube, texture is 2D` could also report an unused conditional input as an error. → [A 2D texture in a cube slot binds the zero cube](../reference/rendering.md#a-2d-texture-in-a-cube-slot-binds-the-zero-cube)
- translucent UI (frosted text bands, button guides, dialog headers) yellow and white. → [Integer views for images a shader declares uint or int](../reference/rendering.md#integer-views-for-images-a-shader-declares-uint-or-int)
- `texture type mismatch: shader declares 2, texture is 9`; the slot read 0. → [Buffer textures read by 1D integer fetches (row wrap)](../reference/rendering.md#buffer-textures-read-by-1d-integer-fetches-row-wrap)
- particle effects drawn at the wrong scale or place, or flickering, where the particle data is a buffer texture at a pool offset that is not a multiple of 16; log line `buffer texture at pool offset …, below Metal's 16-byte alignment`. → [Buffer textures at offsets below 16 bytes](../reference/rendering.md#buffer-textures-at-offsets-below-16-bytes)
- torn digits and a background in blue steps (Rhythm Heaven Groove's latency calibration). → [Automatic block height truncates](../reference/rendering.md#automatic-block-height-truncates)
- magenta (the ASTC error colour) on streamed textures in a sparse pool; `DM_NVN_ZBLOCK` finds such textures (all-zero blocks). → [Sparse textures laid out in 64 KB tiles](../reference/rendering.md#sparse-textures-laid-out-in-64-kb-tiles)
- a CPU-filled texture shuffled into a patchwork of rectangles (OCTOPATH TRAVELER's world map on the traveler selection). → [Sparse textures take the block height of their 64 KB tile](../reference/rendering.md#sparse-textures-take-the-block-height-of-their-64-kb-tile)
- streamed textures read 0 (magenta on Monster Hunter Rise's title screen's clothes). → [Sparse textures bound from their first mapped level](../reference/rendering.md#sparse-textures-bound-from-their-first-mapped-level)
- the process ends at once (the window vanishes), with `-[MTLTextureDescriptorInternal validateWithDevice:]` failing an assertion such as `requests 9 mipmap levels, but the dimensions (1, 1, 1) can only support 1`, or `sampleCount must be > 1 for multisample textures`. → [Texture fields Metal refuses](../reference/rendering.md#texture-fields-metal-refuses)
- ≈13 MB/frame leak. → [Transient render targets shared by storage](../reference/rendering.md#transient-render-targets-shared-by-storage)
- GPU memory grows with every image shown; the memory line's `shared textures` count keeps rising. → [Shared-storage entries taken over by a new texture](../reference/rendering.md#shared-storage-entries-taken-over-by-a-new-texture)
- the whole picture came out darker and more saturated on the Mac and the iPhone: comparing with a Switch screenshot, every channel at every level equalled the Switch value decoded from sRGB once more (0.55 → 0.26, 0.75 → 0.52). → [Render-target views that change the format](../reference/rendering.md#render-target-views-that-change-the-format)
- a clear of, or a format-converting copy into, a texture made without render-target use is declined. → [Render-target use added on demand](../reference/rendering.md#render-target-use-added-on-demand)
- `render target is a compressed-format texture …`; the pass's draws did nothing (the attachment was left out), or the pipeline-descriptor validation aborts the process. → [Compressed textures as render targets through an uncompressed shadow](../reference/rendering.md#compressed-textures-as-render-targets-through-an-uncompressed-shadow)
- the boot aborts in Metal's pipeline validation: `MTLPixelFormatDepth16Unorm is not color renderable`. → [A depth texture drawn through a colour view](../reference/rendering.md#a-depth-texture-drawn-through-a-colour-view)
- a G-buffer target holds only scattered squares (a different order for each 32×32 tile). → [The same texture attached at two colour slots](../reference/rendering.md#the-same-texture-attached-at-two-colour-slots)
- `no render target could get an MTLTexture` (the pass skipped). → [Passes with no render target](../reference/rendering.md#passes-with-no-render-target)
- a black world: everything rendered through a 3D LUT built by layered draws comes out black (every plane went to plane 0); `DM_NVN_PASSDUMP` shows no `L` line. → [Layered passes for vertex shaders that write the layer](../reference/rendering.md#layered-passes-for-vertex-shaders-that-write-the-layer)
- a frame-time spike every few frames (the Metal HUD's frame-time line jumps by several ms at a regular interval) while the scene stands still; `DM_NVN_GPUPROF` over consecutive frames shows the slow frame with about 130 more render passes, each one draw into a 64x64 to 8x8 face of a cube or array level, and the next pass starting late. → [Passes into other layers of one texture level run as one layered pass](../reference/rendering.md#passes-into-other-layers-of-one-texture-level-run-as-one-layered-pass)
- a GPU-bound frame with many passes on the same targets, one after the other, each preceded by a compute encoder of one dispatch (`DM_NVN_GPUPROF`: `compute / copy after pass … dispatches 1` between render passes of the same size); about 4 ms of GPU idle a frame inside command buffers in Metal System Trace. → [Compute dispatches between the draws of a pass run ahead of it](../reference/rendering.md#compute-dispatches-between-the-draws-of-a-pass-run-ahead-of-it)
- a scene drawn only in a small square in the top-left corner of a black screen; speckled and blocky patches; a full-screen overlay showing one tile; the texture dump right after the scene pass shows the picture only in the corner, and `DM_NVN_HILITE` on the scene's shaders lights only the corner. → [Clears of attachments larger than the render pass](../reference/rendering.md#clears-of-attachments-larger-than-the-render-pass)
- `texture clear case not implemented … mask 0x1`. → [A channel mask that covers every channel is a whole clear](../reference/rendering.md#a-channel-mask-that-covers-every-channel-is-a-whole-clear)
- `texture clear case not implemented … mask 0x8` while entering a rendered scene. → [Texture clears with partial channel masks or regions](../reference/rendering.md#texture-clears-with-partial-channel-masks-or-regions)
- red lines for unimplemented mid-pass, partial-mask and partial-scissor clears (the clears were dropped); `depth-stencil clear with a scissor or partial stencil mask, cleared whole` (logged once). → [Clears inside a pass, with a partial mask or a partial scissor](../reference/rendering.md#clears-inside-a-pass-with-a-partial-mask-or-a-partial-scissor)
- a tile grid in Ultrahand and Recall highlights; an `EQUAL` depth test rejects fragments writing the same depth as a cleared Depth16 target. → [Depth16 load-clears match fragment writes](../reference/rendering.md#depth16-load-clears-match-fragment-writes)
- solid magenta blocks, exactly (255, 0, 255), hard-edged and aligned to the 16-pixel grid (16×16, sometimes two stacked): Super Mario 3D World showed them only on the iPhone; Captain Toad on a Mac, Apple M6, in about half the frames of the opening course, moving with the falling leaves. → [Same-pass feedback read through a snapshot](../reference/rendering.md#same-pass-feedback-read-through-a-snapshot)
- text a game renders into textures for the title and the menus comes out upside down, while the scene looks right. → [Lower-left window origin](../reference/rendering.md#lower-left-window-origin)
- a pink window with every command buffer ignored while headless runs look right: the first presents fail on the display command buffer with `kIOGPUCommandBufferCallbackErrorPageFault`, and after a few of those macOS ignores every submission of the process ("Ignored (for causing prior/excessive GPU errors)"). → [The residency set committed before a present](../reference/rendering.md#the-residency-set-committed-before-a-present)
- a game that renders below the screen's resolution looks soft on a phone, in a large Mac window or on a 4K screen. → [The present upscales through MetalFX](../reference/rendering.md#the-present-upscales-through-metalfx)
- undefined values blended into attachments the fragment shader leaves alone. → [No writes to colour outputs the shader does not write](../reference/rendering.md#no-writes-to-colour-outputs-the-shader-does-not-write)
- `nvnBlendStateSetAdvancedMode 8` (SRC_OVER) logged and blended with the state's own functions. → [Advanced blend modes as Porter-Duff factors](../reference/rendering.md#advanced-blend-modes-as-porter-duff-factors)
- striped lighting: black and white bands that follow depth on every lit surface, as if every pixel were in or out of shadow at random. → [Stencil-mode texture views read through `X32_Stencil8`](../reference/rendering.md#stencil-mode-texture-views-read-through-x32_stencil8)
- a character drawn as a dithered silhouette inside a dithered square (DRAGON QUEST VII Reimagined's hero). → [Stencil-mode textures from the texture builder](../reference/rendering.md#stencil-mode-textures-from-the-texture-builder)
- characters (skinned models) invisible or stretched into streaks while the level renders; `vertex attribute format … does not match shader input type …` for a remaining mismatch. → [Integer vertex inputs](../reference/rendering.md#integer-vertex-inputs)
- red lines 89 and 96 (`vconv_bind`, the CPU conversion every draw); about a quarter of Age of Calamity's replay thread in battle. → [Shadow vertex inputs](../reference/rendering.md#shadow-vertex-inputs)
- an unsigned iOS build reports `[RED] pulling library ... not usable (no library)` and its draws wait for pipelines even with the profile's `pso_mtl4 on`, or packaging with `IOS_PULL=1` fails with `SKIPS[@]: unbound variable`. → [Pulling vertex inputs](../reference/rendering.md#pulling-vertex-inputs)
- `Vertex attribute m_36(5) of type uint4 cannot be read using MTLAttributeFormatHalf2` (draws dropped: black silhouettes); UVs collapse onto one texel (flat tan characters); vertices far out of view (negative 16-bit values widened with zeros). → [CPU conversion of vertex attributes the input type cannot take](../reference/rendering.md#cpu-conversion-of-vertex-attributes-the-input-type-cannot-take)
- `vertex attribute format … not mapped` (printed once). → [Vertex formats Metal lacks](../reference/rendering.md#vertex-formats-metal-lacks)
- the assertion `buffer index (31) must be < 31`. → [Vertex streams 14 and 15 at Metal slots 14 and 15](../reference/rendering.md#vertex-streams-14-and-15-at-metal-slots-14-and-15)
- scenes and characters black, only foliage, light shafts and the HUD drawn; pass dumps full of `Z … draw skipped: no program bound`. → [Programs bound per stage](../reference/rendering.md#programs-bound-per-stage)
- `[RED] failed to create render pipeline (vertex 790573a52b9c5053_b fragment f39fb42850f50ecd_b): Fragment input(s) user(locn0),user(locn1) … not written by vertex shader`, once on entering the first investigation; `texture type mismatch: shader declares a cube, texture is 2D` (a pixel shader run with another pair's bindings). → [Composite program taken again after a replay state restore](../reference/rendering.md#composite-program-taken-again-after-a-replay-state-restore)
- `no program bound before the draw`, `program has no vertex shader` (a draw after a dispatch is dropped); `the dispatched program has no compute shader` (a dispatch after a graphics bind). → [Compute programs bound apart from graphics programs](../reference/rendering.md#compute-programs-bound-apart-from-graphics-programs)
- a red line: the 8-bit index buffer had GPU-side writes in the submission (indices read stale). → [8-bit indices widened on the GPU after a write in the same submission](../reference/rendering.md#8-bit-indices-widened-on-the-gpu-after-a-write-in-the-same-submission)
- indirect draws whose record the GPU writes earlier in the frame cannot be read on the CPU at replay; GPU-driven effects drawn as indirect quads, which Metal has no primitive for. → [Indirect draws and dispatches read by the GPU](../reference/rendering.md#indirect-draws-and-dispatches-read-by-the-gpu)
- an empty G-buffer pass (the title screen showed only the UI); later, the submitting thread waiting for the GPU before each such draw (36–54 fps in Kamura Village on an iPhone). → [Indirect-count multi-draws](../reference/rendering.md#indirect-count-multi-draws)
- characters collapsed into one thin spike (vertex streams read from feedback buffers that were never written); a character covered by a solid box while it moves (its fur shells pulled toward lagged positions that were never written); a pass dump shows draws with a vertex shader and no fragment shader (`fs=-`) before the draws that read them, and `Y tf begin … written 0/0/0/0` with no `T … tf capture` line. → [Transform feedback captured by a vertex entry point](../reference/rendering.md#transform-feedback-captured-by-a-vertex-entry-point)
- `SIGSEGV` in `-[AGXG18GFamilyComputeContext_mtlnext performEndEncoding]` (from `rp_begin_ex_`, or in its `dealloc` on the encoding thread); Metal validation (`MTL_DEBUG_LAYER=1 MTL_DEBUG_LAYER_ERROR_MODE=nslog`) names it: "Command buffer already has an open command encoder". → [Helper encoders end the open copy encoder first](../reference/rendering.md#helper-encoders-end-the-open-copy-encoder-first)
- the whole picture upside down (Absolum's title logo and "Press Any Button" mirrored top to bottom); a red-reporting stub for `nvnCommandBufferSetViewportSwizzles`. → [Viewport swizzles applied as a flipped viewport](../reference/rendering.md#viewport-swizzles-applied-as-a-flipped-viewport)
- tall blue / textured panels that flickered frame to frame: the fountain's vertex shader pushed the water surface to the top of the screen. → [Metal 4 does not order operations inside one encoder](../reference/rendering.md#metal-4-does-not-order-operations-inside-one-encoder)
- a buffer copy, inline update or fill completes, but a following copy through another Metal buffer over the same allocation reads stale bytes. → [Buffer copies through aliased Metal addresses](../reference/rendering.md#buffer-copies-through-aliased-metal-addresses)
- many render passes with one draw each and high submit time: Metroid Dread's cutscene frames had about 180 passes with one draw each (about 5 ms of submit time per frame on the Mac). → [Inline uniform updates inside a render pass](../reference/rendering.md#inline-uniform-updates-inside-a-render-pass)
- hundreds of render passes a frame and heavy attachment traffic when a game updates a small part of a large uniform block before each draw group. → [Partial-cover uniform shadows keep passes open](../reference/rendering.md#partial-cover-uniform-shadows-keep-passes-open)
- `stage 0 cb5 has no uniform buffer bound`. → [An unbound uniform slot reads the zero bank](../reference/rendering.md#an-unbound-uniform-slot-reads-the-zero-bank)
- GPU time per frame doubles with many small dispatches (Age of Calamity: GPU 9 → 18 ms a frame on the Mac; the iPhone's 15 → 51 ms, 17 fps). → [Compute dispatches share the copy encoder](../reference/rendering.md#compute-dispatches-share-the-copy-encoder)
- dialog boxes with holes the size of their text, and white specks where text faded. → [Fragment-ordering barriers between draws that write images](../reference/rendering.md#fragment-ordering-barriers-between-draws-that-write-images)
- a texture copied from a staging buffer shows another texture's blocks (Catherine: Full Body's cutscene subtitle band a hard-edged dark box with a magenta stroke through it). → [A segment committed after a buffer → texture copy](../reference/rendering.md#a-segment-committed-after-a-buffer--texture-copy)
- a scaled texture copy skipped with a red line (Metal blits cannot scale); format-changing, depth-stencil and mirrored copies. → [Copies a blit cannot do, drawn](../reference/rendering.md#copies-a-blit-cannot-do-drawn)
- `[RED] Downsample case not implemented: 320x176 1 samples format 70 → 80x48`; a missing bloom. → [`Downsample` of a single-sample texture](../reference/rendering.md#downsample-of-a-single-sample-texture)
- no ambient occlusion (Mac); on a device the result depends on whatever that memory holds. → [Depth-stencil copies carry the stencil](../reference/rendering.md#depth-stencil-copies-carry-the-stencil)
- `DM_NVN_GPUPROF=every:1` prints no per-frame reports and fills its timestamp heap across frames. → [Periodic GPU profiles close at frame boundaries](../reference/rendering.md#periodic-gpu-profiles-close-at-frame-boundaries)
- the 3D scene black (targets cleared again before they are read); `[RED] SetRenderEnableConditional: the host draws anyway`; with a game that skips clears under render conditions, scenes black behind the HUD (Mario vs. Donkey Kong's levels, 1.0.1). → [Conditional rendering evaluated at replay](../reference/rendering.md#conditional-rendering-evaluated-at-replay)
- no SPIR-V file in the RomFS; SPIRV-Cross refuses a module with "Struct member does not have ArrayStride set". → [Vulkan shaders generated at run time](../reference/rendering.md#vulkan-shaders-generated-at-run-time)
- a crash in `bind_res` reading a freed view's texture (Super Mario Galaxy 2 on an iPhone, element 1 of the 8-texture array, when the ship took off after the first galaxy; GitHub issue 68). → [Descriptors hold the Metal objects they were written with](../reference/rendering.md#descriptors-hold-the-metal-objects-they-were-written-with)
- Metal refuses the pipeline: "Fragment shader does not write to render target color(0), index(1)". → [Dual-source blending from output location 1](../reference/rendering.md#dual-source-blending-from-output-location-1)
- Metal's validation aborts on a buffer layout no mapped attribute uses. → [Scaled and three-component vertex formats](../reference/rendering.md#scaled-and-three-component-vertex-formats)
- menus 1.5x too big in handheld mode (the file-creation dialog cut off at the right edge). → [Viewport and scissor persist across render passes](../reference/rendering.md#viewport-and-scissor-persist-across-render-passes)
- `draw outside a render pass`; the rest of the pass was dropped. → [Copies inside a render pass](../reference/rendering.md#copies-inside-a-render-pass)
- an assert (a stripped trap, `main+0x4d26e0`) when the surface does not list `preTransform` INHERIT. → [Swapchain pre-transform and layer crop](../reference/rendering.md#swapchain-pre-transform-and-layer-crop)
- GX points and lines drawn as one-pixel points and lines; a red line for the sampler LOD bias. → [Not translated in the Vulkan layer: geometry shaders and LOD bias](../reference/rendering.md#not-translated-in-the-vulkan-layer-geometry-shaders-and-lod-bias)
- `UNIMPL eglGetDisplay`, then `Break` right after `nv::InitializeGraphics` and `vi::OpenDefaultDisplay` (`main+0x5ed9d0`). → [Games that render with desktop OpenGL through EGL](../reference/rendering.md#games-that-render-with-desktop-opengl-through-egl)
- the NSP script's provisional profile said Vulkan, and the capture boot crashed in the GL layer. → [Telling a GL game from an NVN or Vulkan one](../reference/rendering.md#telling-a-gl-game-from-an-nvn-or-vulkan-one)
- the NSP script took the game for an OpenGL one (`main imports EGL and names glShaderSource`), the GL shader capture found no shader, and the capture boot stopped with `[nvn-mtl] FATAL cannot read the shader map` from `h_nvnQueueSubmitCommands` called in an NRO (`nro8+0xc10d0`). → [NVN in NROs under an SDL main that names GL](../reference/rendering.md#nvn-in-nros-under-an-sdl-main-that-names-gl)
- a jump to address 0 right after `glGetFloatv(0xb12)` (`lr=main+0x2d58c4`). → [Which GL functions a game calls](../reference/rendering.md#which-gl-functions-a-game-calls)
- in a capture run every program links with no uniforms; the game's first `Shader:send` raises a Lua error and, on the Switch, its error handler quits (Any Lua error quits a LÖVE game). → [GL shaders put together at run time and captured](../reference/rendering.md#gl-shaders-put-together-at-run-time-and-captured)

## Shaders

- `shader_split.py` finds 0 shaders in a RomFS of zstd files named `.zst`. → [Zstd files recognised by their magic](../reference/shaders.md#zstd-files-recognised-by-their-magic)
- the game asks for shaders the map does not have (`[RED] shader ... is not in the shader map`, hundreds of lines), and the split finds far fewer shaders than the game uses (121 against 27,288 on Kirby and the Forgotten Land). → [HAL's `.cmp` containers: a size-prefixed frame](../reference/shaders.md#hals-cmp-containers-a-size-prefixed-frame)
- a provisional split finds only a fraction of the shaders (3,126 of Pokémon Sword's 41,516). → [BNSH entries of GFPAK archives](../reference/shaders.md#bnsh-entries-of-gfpak-archives)
- the split found no shader in the game (0 shaders). → [GLSLC outputs holding several stages](../reference/shaders.md#glslc-outputs-holding-several-stages)
- an NVN game's split finds none of its shipped shaders, and the ones it compiles at run time were not captured: the game's renderer is in NROs that call `glslcCompile`, and its whole RomFS is one zip. → [GLSLC outputs in a zip archive, and those NROs compile at run time](../reference/shaders.md#glslc-outputs-in-a-zip-archive-and-those-nros-compile-at-run-time)
- 24 shaders before the control-length fix, 1,355 after. → [SPKG packages in KTGL LINKDATA](../reference/shaders.md#spkg-packages-in-ktgl-linkdata)
- `[RED] ... PKZ version 0x10000: only 0x20000 is known` stops the shader split. → [PKZ version 1 archives](../reference/shaders.md#pkz-version-1-archives)
- the split finds zero shaders and refuses the shader build, although the CPK's DAT archives contain the objects passed to NVN at boot. → [Size-delimited PlatinumGames shader objects](../reference/shaders.md#size-delimited-platinumgames-shader-objects)
- the split finds no shaders, although `main` contains NVN control sections; it reports that no data record or code-address pair identifies their code areas. → [Needle shader containers in main and GFD archives](../reference/shaders.md#needle-shader-containers-in-main-and-gfd-archives)
- shaders the game draws are missing from the map (`DM_NVN_SHDUMP`), in no RomFS file and no module, stored or LZ4, and not compiled at run time. → [Shaders in a zlib stream in main (YEBIS .tfxo)](../reference/shaders.md#shaders-in-a-zlib-stream-in-main-yebis-tfxo)
- two `[RED] shader … is not in the shader map` lines and `program has no vertex shader` as the opening movie starts; every movie drew white. → [Loose control sections and code areas in main (Bink 2)](../reference/shaders.md#loose-control-sections-and-code-areas-in-main-bink-2)
- the provisional split finds only `main`'s 294 GLSLC outputs; the 3D scene and the title logo are magenta, with `[RED] shader … is not in the shader map` lines. → [SNVN program records in Retro Studios' RFRM forms](../reference/shaders.md#snvn-program-records-in-retro-studios-rfrm-forms)
- the split stopped with `no bundle has a Shader type tree of the same hash to borrow`. → [Unity Shader layouts written out for players without bundles](../reference/shaders.md#unity-shader-layouts-written-out-for-players-without-bundles)
- the 3D battle scene was black behind a correct UI, with `[RED] shader 854a8afc9d07f88d is not in the shader map` and `the dispatched program has no compute shader`. → [Unity ComputeShader objects](../reference/shaders.md#unity-computeshader-objects)
- black, jagged holes in the ground of a map (whole tiles of the terrain mesh missing while others draw), with about 25 distinct `[RED] shader … is not in the shader map` keys and `program has no vertex shader`, on a Unity game whose `Shader` objects all split cleanly. → [GLSLC outputs in a Unity TextAsset](../reference/shaders.md#glslc-outputs-in-a-unity-textasset)
- `the RomFS has Unreal paks, but none … holds a shader code archive`, then `the shader split found no shaders in main or the RomFS`. → [Unreal Engine 4.27 shaders inline in cooked packages (LZ4)](../reference/shaders.md#unreal-engine-427-shaders-inline-in-cooked-packages-lz4)
- shaders reported missing at random, and their dumped control sections are garbage (Unity). → [Program keys computed inside `nvnProgramSetShaders`](../reference/shaders.md#program-keys-computed-inside-nvnprogramsetshaders)
- 12 compute shaders (particles, post effects) translated into an endless loop that hung the GPU at the first gameplay scene; SPIRV-Cross failed on 7 shaders instead of 2 (SPIRV-Cross parse failures). → [Exact program start for the decoder](../reference/shaders.md#exact-program-start-for-the-decoder)
- GLSLC outputs fail the reader's check and are dropped (44 of DARK SOULS: REMASTERED's `main`'s 72 outputs and most of its archives' pixel shaders). → [GLSLC outputs read through their section headers](../reference/shaders.md#glslc-outputs-read-through-their-section-headers)
- `shader_split.py` finds no stage for vertex shaders and stops at the first captured output (`no GLSLC output`). Translated, every post pass and the window draw one texel's colour (a black screen with sound); every varying at (0, 0, 0, 1). → [VertexA and VertexB parts merged into one vertex shader](../reference/shaders.md#vertexa-and-vertexb-parts-merged-into-one-vertex-shader)
- SPIRV-Cross can't parse the SPIR-V (`nullptr` exception). → [SPIRV-Cross parse failures](../reference/shaders.md#spirv-cross-parse-failures)
- `Fragment input(s) user(locnN) mismatching vertex shader output type(s) or not written by vertex shader` and the draw is skipped; the host reports `[RED] failed to create render pipeline (vertex … fragment …)`. → [Pixel shader inputs the vertex shader does not write](../reference/shaders.md#pixel-shader-inputs-the-vertex-shader-does-not-write)
- outdoors dim and nothing casts a sun shadow (every shadow-map lookup fails). → [Unwritten components of a written output start as (0, 0, 0, 1)](../reference/shaders.md#unwritten-components-of-a-written-output-start-as-0-0-0-1)
- the ground kept stale 32×32 blocks where the G-buffer draw failed the depth test: blocks of a stale image where a depth pre-pass and a later pass with other vertex shaders meet (Odyssey: 32×32 blocks on every fourth frame). → [Position invariance across shaders](../reference/shaders.md#position-invariance-across-shaders)
- the half of Mario facing the camera's left was white (GitHub issue 72, on an iPhone). → [min, max and clamp with a NaN operand](../reference/shaders.md#min-max-and-clamp-with-a-nan-operand)
- a pipeline red line for a float output meeting an integer attachment (the red line prints the row to add); a BC encoder's pipeline fails. → [Integer fragment outputs declared by hand](../reference/shaders.md#integer-fragment-outputs-declared-by-hand)
- `failed to create render pipeline … output of type float4 is not compatible with a MTLPixelFormatR32Uint color attachment` (or `MTLPixelFormatRGBA16Uint`); every draw into the target skipped. → [Integer entry points for integer colour outputs](../reference/shaders.md#integer-entry-points-for-integer-colour-outputs)
- `failed to create render pipeline … Cannot convert attribute …`; draws missing (a pipeline that fails to build). → [Integer-typed vertex inputs fed normalized formats](../reference/shaders.md#integer-typed-vertex-inputs-fed-normalized-formats)
- outdoors the whole screen blurred (depth of field out of focus everywhere). → [Depth mode near = 0 needs the per-mode entry points](../reference/shaders.md#depth-mode-near--0-needs-the-per-mode-entry-points)
- `SPIRV-Cross threw an exception: Subgroup builtins are not available in this type of function`. → [Subgroup operations rewritten for a one-lane subgroup](../reference/shaders.md#subgroup-operations-rewritten-for-a-one-lane-subgroup)
- the tone mapper read an empty LUT and the screen came out a flat blue. → [Geometry shaders that only pick the layer](../reference/shaders.md#geometry-shaders-that-only-pick-the-layer)
- a geometry shader fails to compile with `unknown main0_out`: SPIRV-Cross writes `unknown main0_out main0()` for the geometry stage, and the shader does not build. → [Geometry shaders with no Metal stage](../reference/shaders.md#geometry-shaders-with-no-metal-stage)
- the geometry kernel compiles, but its `_bgv.metal` vertex reader fails with `use of undeclared identifier 'gl_BuiltIn_5253'` and `member reference base type 'int' is not a structure or union`. → [Geometry reader viewport masks](../reference/shaders.md#geometry-reader-viewport-masks)
- a passthrough geometry kernel writes beyond its vertex and raw-index scratch regions, and compaction reads the wrong groups; corruption can reach the following primitive-map buffers without a red diagnostic. → [Passthrough geometry output bounds follow input topology](../reference/shaders.md#passthrough-geometry-output-bounds-follow-input-topology)
- a geometry kernel compiles and runs its storage-buffer side effects, but contains no `geometry_vb_output` binding and fills its index stream with restart markers; its following raster pass draws no geometry. → [Passthrough geometry kernels lose raster vertices](../reference/shaders.md#passthrough-geometry-kernels-lose-raster-vertices)
- geometry-heavy frames have a large submission wall/CPU gap despite short GPU execution; stack samples spend most of the main thread in `geo_draw` → `mdi_wait` → shared-event wait, with index sorting another substantial cost. → [Geometry capture waits for every indexed draw](../reference/shaders.md#geometry-capture-waits-for-every-indexed-draw)
- geometry-heavy frames remain GPU-bound after CPU readback waits are removed; encoder timestamps attribute most compaction time to the offset scan rather than the geometry shader or index writes. → [Geometry compaction serial prefix scan](../reference/shaders.md#geometry-compaction-serial-prefix-scan)
- `[RED] geometry draw needs 261 MiB of scratch, above the 256 MiB bound` (or `exceeds the capture or invocation bound`); the draw is skipped. → [Geometry draws above the capture scratch bound](../reference/shaders.md#geometry-draws-above-the-capture-scratch-bound)
- `primitive type 14 not implemented`; patch draws skipped. → [Tessellation stages are not drawn](../reference/shaders.md#tessellation-stages-are-not-drawn)
- a vertex or compute shader reads zeros from NVN's driver segment `c0`. → [Driver-segment reads outside fragment shaders](../reference/shaders.md#driver-segment-reads-outside-fragment-shaders)
- flickering hard-edged white tiles (tiled lighting with every tile row getting row 0's or other rows' lights). → [Compute `c0`: dispatch size and uniform buffer table](../reference/shaders.md#compute-c0-dispatch-size-and-uniform-buffer-table)
- `[RED] shader ... reflection conversion failed: B binding gp_s0 has no resolved slot number`; a geometry shader reading driver segment `c0` reports that its storage-buffer table base was never measured. → [Geometry-stage storage buffer table](../reference/shaders.md#geometry-stage-storage-buffer-table)
- a storage buffer the shader stores to or uses atomically has `rw: false` in its generated reflection; replay does not record its GPU writes for dependent buffer reads. → [Storage-buffer write flag in translation metadata](../reference/shaders.md#storage-buffer-write-flag-in-translation-metadata)
- point sprites of size 0 (Odyssey's Cap Kingdom fog never parted around Mario). → [Graphics `c0 + 0x610`: the largest point size](../reference/shaders.md#graphics-c0--0x610-the-largest-point-size)
- occlusion queries that always return 0 samples (Z-A: characters' legs folded back from the hips once they walked); every instanced draw's transform taken for instance 0. → [Graphics `c0 + 0x644`: the draw's base instance](../reference/shaders.md#graphics-c0--0x644-the-draws-base-instance)
- a menu's labels drawn as plain bars, other menus empty except for the cursor (one pool's textures overwritten by another's); a black screen when IDs past a fixed table read as empty slots. → [Texture and sampler pools with overlapping IDs](../reference/shaders.md#texture-and-sampler-pools-with-overlapping-ids)
- red lines from the list of command buffers that bound a non-first pool (6,734 in one DARK SOULS: REMASTERED run). → [Bases of bound handles kept in the command buffer](../reference/shaders.md#bases-of-bound-handles-kept-in-the-command-buffer)
- distant walls and floors smeared sideways (DARK SOULS: REMASTERED): tiling textures took a clamp-to-edge sampler and repeated their edge column. → [Handles from uniform buffers take the bound pools' bases](../reference/shaders.md#handles-from-uniform-buffers-take-the-bound-pools-bases)
- the 3D scene black, only particles and the HUD drawn; pass dump `B` lines all `tid=0 dummy`. → [Deferred texture binds read at execution](../reference/shaders.md#deferred-texture-binds-read-at-execution)
- bindless handles read from a uniform buffer name the wrong texture when the game writes them earlier in the same submission. → [Handles in uniform buffers written earlier in the same submission](../reference/shaders.md#handles-in-uniform-buffers-written-earlier-in-the-same-submission)
- a storage buffer reported with `cb_slot` 3, which had no NVN slot. → [Storage buffer addresses in the game's own uniform buffer](../reference/shaders.md#storage-buffer-addresses-in-the-games-own-uniform-buffer)
- `no resolved slot number`, the shader does not load; the translation has a 32-entry texture-pool array (`fp_t2d_cb0_40000000`, handle type Direct). → [Bindless handles through a loop phi](../reference/shaders.md#bindless-handles-through-a-loop-phi)
- none in the log: texture reads come back 0. Particle meshes collapse to a point (their scale reads 0), so effects are missing or show as dark patches. The translator's own message (`Failed to find handle source for bindless access of type "textureBuffer"`) used to be dropped, because `dmsh_xlate`'s accessor had no `Log`; its messages now go into the shader's notes, marked `translator: `, and the build summary counts them apart from unanswered queries. → [Bindless reads whose handle phi also carries other values](../reference/shaders.md#bindless-reads-whose-handle-phi-also-carries-other-values)
- the shaders' bindless arrays have no slot and used not to load; the translator falls back to a 32-entry array such as `array<texturecube<float>, 32> fp_tcube_cb0_40000000`. → [Texture slots picked at run time](../reference/shaders.md#texture-slots-picked-at-run-time)
- Ryujinx's fallback arrays (`fp_t2d_cb0_40000000`) in pixel shaders whose handle comes from the game's own uniform buffers; the shaders do not load and their draws are skipped. → [A texture chosen at run time between two uniform-buffer handles](../reference/shaders.md#a-texture-chosen-at-run-time-between-two-uniform-buffer-handles)
- the host stops at the shader's first load: `unexpected argument buffer layout: encodedLength=640 maxAid=48`. → [An array of handles in a uniform buffer](../reference/shaders.md#an-array-of-handles-in-a-uniform-buffer)
- `shaders with a binding whose slot was not decoded 588`; shadow cascades read through `array<texture2d_array<float>, 32> fp_t2das_cb2_0`. → [An array of handles from the driver table c2](../reference/shaders.md#an-array-of-handles-from-the-driver-table-c2)
- characters and props glowing white, about 10⁴ too bright, in DRAGON QUEST VII Reimagined's opening cutscene only, while walls and gameplay look right. → [A texture slot that shares its c2 word with an image slot](../reference/shaders.md#a-texture-slot-that-shares-its-c2-word-with-an-image-slot)
- `[RED] shader … reflection conversion failed: 66 bindings, over the limit 64`, then `failed to load`, and the draws with it are dropped (a black map). → [More than 64 bindings in one shader](../reference/shaders.md#more-than-64-bindings-in-one-shader)
- the replay put a texture resource ID where the shader wanted an address; with the old 64 KB dummy buffer, pointers in the game's objects and in the host's program objects got their upper 4 bytes replaced and the game or the replay crashed, or `kIOGPUCommandBufferCallbackErrorPageFault`, after which macOS ignores the process's command buffers (GitHub issue #101). → [Image atomics](../reference/shaders.md#image-atomics)
- `image atomics: unsupported or overflowing IMG extent` at the first dispatch, despite a valid four-byte counter buffer. → [Buffer image reflection keeps its texture type](../reference/shaders.md#buffer-image-reflection-keeps-its-texture-type)
- Metal shader validation reports invalid image-atomic stores even with an image-sized scratch buffer; without validation, GPU page faults can freeze rendering. → [Bounded MSL 2.3 atomic emulation](../reference/shaders.md#bounded-msl-23-atomic-emulation)
- shaders missing from the map that no game file holds. → [Built-in shaders compiled with the game's own GLSLC](../reference/shaders.md#built-in-shaders-compiled-with-the-games-own-glslc)
- a null read at `main+0x3316dc` in `nnMain`, right after the window setup (the program object's interface pointers at +0xd0 / +0xd8 both null). → [GLSLC GPU code version against the driver's range](../reference/shaders.md#glslc-gpu-code-version-against-the-drivers-range)
- a self-contained Mac app (`--platform mac-app`) logs `pipeline prebuild: no .../Resources/dm/shader_pairs.tsv, nothing to build` although every shader library is there; it draws no hybrid stand-ins, and each pipeline seen for the first time compiles on the submit thread (frames of 100–550 ms). → [Shader-pair tables in a Mac app](../reference/shaders.md#shader-pair-tables-in-a-mac-app)
- a truncated `.mtl4a` reaches `MTL4ArchiveImpl::loadFromURL`; the bundle reports coverage with `0 of 0 probed bases found`; rebuilt shader libraries reuse an archive of their old binaries; or packing fails with `pso_offline: no base to build` when every eligible pair has function constants. → [Offline pipeline archive reuse and fallback](../reference/shaders.md#offline-pipeline-archive-reuse-and-fallback)
- the user cache folder (`getconf DARWIN_USER_CACHE_DIR`, then `com.apple.gpuarchiver/`) fills with `gpuarchiver-*` folders of 0.3–5 MB each, one per pipeline archive flush, and they stay after the game exits: 456 folders, 2.5 GB, on one Mac after two days of NVN game runs. On iOS they stay in the app's own cache folder. → [Metal's build folders left by pipeline archive flushes](../reference/shaders.md#metals-build-folders-left-by-pipeline-archive-flushes)
- identical render pipelines compile repeatedly under different keys, lengthening startup prewarm and adding pipeline misses during play. → [Pipeline keys omit unused colour state](../reference/shaders.md#pipeline-keys-omit-unused-colour-state)
- a vertex shader whose pairs changed was restored unpadded from `cas/`. → [Shader cache key covering the pairs](../reference/shaders.md#shader-cache-key-covering-the-pairs)
- `fragmentFunction main0 cannot be used to build a pipeline state` (a Metal validation assertion). → [Function constants specialized at load](../reference/shaders.md#function-constants-specialized-at-load)
- a pipeline for a vertex shader that writes `render_target_array_index` cannot be built. → [Layer-writing vertex shaders get the triangle class](../reference/shaders.md#layer-writing-vertex-shaders-get-the-triangle-class)
- the picture bright green and white from some scene on, in runs with pipelines compiled on demand (prewarm lists off or short) and in none with `DM_NVN_PREDICT=0`. → [The precompile look-ahead restores the scissor](../reference/shaders.md#the-precompile-look-ahead-restores-the-scissor)
- a GPU frame capture (`DM_GPU_CAPTURE`, or Xcode with `MTL_CAPTURE_ENABLED=1`) fails with `Capturing Render pipeline specialization is not supported`, or the capture layer crashes on the pipeline archive; a capture of the `MTLDevice` is refused. → [GPU frame captures need pipelines built through the device](../reference/shaders.md#gpu-frame-captures-need-pipelines-built-through-the-device)
- the first boot sat on the loading clock for about a minute, the CPU idle, with every file read done after 12 s. → [A cold Metal cache looks like a long load](../reference/shaders.md#a-cold-metal-cache-looks-like-a-long-load)

## Game state

- "stuck" at a screen with one draw per frame. → [Most draws are in command buffers replayed later](../reference/game-state.md#most-draws-are-in-command-buffers-replayed-later)
- menus ignore A. → [Buttons mapped by position: B confirms](../reference/game-state.md#buttons-mapped-by-position-b-confirms)
- a crash in `main+0x339c00` a second or two into the title, in love-nx's video module teardown (`love::video::theora::Video` → `~Worker`; its thread released the worker that the closing module deletes too). → [Any Lua error quits a LÖVE game](../reference/game-state.md#any-lua-error-quits-a-löve-game)
- the TV latency calibration ("press A when you hear the fourth beat") ignores A. → [TV latency calibration's late, beat-timed listening window](../reference/game-state.md#tv-latency-calibrations-late-beat-timed-listening-window)
- in a scripted run, a screen goes back by itself right after a confirm; the log shows `swkbd: … → no window, treated as cancel`. → [The software keyboard in scripted runs (`DM_KBD`)](../reference/game-state.md#the-software-keyboard-in-scripted-runs-dm_kbd)
- a player join screen that ignores A (a character select with four "L + R to join" slots after the title). → [Player join screens (`hid::StartLrAssignmentMode`)](../reference/game-state.md#player-join-screens-hidstartlrassignmentmode)