nxnative-easy/docs/agents/symptoms.md

Symptom index

One line per symptom in the subsystem references: 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

• decompress NSZ stops immediately with nsz: error: unrecognized arguments: --keys …. → 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
• jump table <addr> assertion in patch_nso.py, in a Unity / IL2CPP main. → 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
• 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
• 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
• 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
• 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
• jump table <addr> assertion, entries relative to an adr. → 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)
• 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
• jump table <addr> assertion in patch_nso.py, in a Unity / IL2CPP main, at a blr x18. → 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
• jump table 53e9c while rewriting Warm Snow 2.1.4's Unity IL2CPP main. → 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
• branch into window <addr> assertion. → 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
• 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
• 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
• B() range assertion in patch_nso.py (site_plain), only for one module. → 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
• 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
• 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
• 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
• the rewrite never finishes, the Mac swaps, the rewriter's footprint reaches 100 GB. → 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
• RuntimeError: 788 ldr x18, #0xd1eb0 in patch_nso.py, or any rewrite site in data. → 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
• 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
• SIGILL / trap on a system register read. → System register reads that macOS traps
• every pointer in .data / the GOT is a module offset, crashes everywhere. → 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
• 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
• 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
• 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
• 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
• 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
• 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
• 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
• 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
• nn::diag abort at sdk+0x12dad0 in nninitStartup, called from main+0x756310. → .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
• 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
• 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
• 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
• 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
• 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
• C++ exception aborts in nn::ro::detail::GetExceptionInfo. → svcQueryMemory must report each module's real layout
• MapPhysicalMemory faults on part of a page. → 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
• a write through a null pointer at +0x1c0 during startup. → GetInfo(UserExceptionContextAddress) 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
• 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
• 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
• 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
• 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
• 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
• GPU memory grows with repeated nvnTextureReadTexels calls on a long-lived game thread, even after each readback completes. → 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
• per-core job queues never drained. → 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
• 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)
• in garbage-collected titles (Unity / IL2CPP), live objects freed, with their finalizers releasing native resources. → 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
• several threads crash at once and the dumps interleave, then the process hangs instead of exiting. → 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
• 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
• 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
• 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)
• a guest thread keeps a core at 100% with billions of SleepThread calls. → 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)
• 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
• 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
• 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

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
• a game update aborts at boot where the base game ran. → 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
• 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
• abort in sm::Initialize under nn::friends::GetBlockedUserList after the opening movie. → SDK 4's friends::GetBlockedUserList 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
• IL2CPP "Could not open …/global-metadata.dat" (then a crash in its logger). → The SDK's own fs::IsMounted 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
• an Atk task aborts in a switch default (UnexpectedDefaultImpl, then AbortImpl) while a stream sound loads. → 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
• [RED] fs ReadFile into … failed at +0 (EFAULT): VM region … protection 1, now and then. → ReadFile into write-protected texture pool pages
• fs … not found lines with DM_FS=1. → 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
• the SDK's own code opened fsp-srv and aborted, leaving the save writes uncommitted. → fs::Commit with a list of mounts
• SIGSEGV at address 0 in nn::fs::GetSaveDataSizeMax, about 13 minutes into a new game. → 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
• the island lives in device save data, which the host did not mount. → Device save data on the account save's 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
• abort in fs::detail::GetFileSystemProxyServiceObject under fs::QueryMountSystemDataCacheSize (main+0x8f23bc). → System data stand-in for the MiiModel archive
• DLC the player owns is not unlocked. → 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
• 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
• 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
• 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
• motion moves never happen; shaking does nothing (Super Mario Odyssey: cap throws by shaking). → 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
• abort in nn::sm::Initialize under nn::hid::VibrationNode::Update. → Vibration values flushed by the SDK's 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
• 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
• the first boot aborted in hid::GetMouseState (the SDK's mouse resource was never initialized). → 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)
• undefined irsensor imports found from the import list (Listing a game's unhooked imports before they are met). → 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
• 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
• 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
• 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
• 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
• 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
• 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
• SIGSEGV in vi::SetLayerCrop. → vi layer and display calls without vi service objects
• SIGSEGV in android::Surface::getQueuedFrameNumber under nn::vi::GetLatestFrameNumber. → Layer frame numbers
• SIGSEGV in vi::GetDefaultDisplayPanelIdentifier (main+0xa9a4, before the window). → 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
• abort in nn::sm::Initialize under nn::oe::FinishStartupLogo, right after the first frames. → The startup logo
• null read in oe::InitializeCopyrightFrameBuffer, right after the window setup. → 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
• 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
• 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
• 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
• 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
• [RED] sf: the game connects to service mii:e … mii:u itself, then an abort. → 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
• abort in nn::sm::Initialize under nn::pctl::IsFreeCommunicationAvailable (Engage, entering its first battle map). → 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
• 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
• 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
• the first comparison in nnMain aborted in sm. → 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
• 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
• abort in nn::sm::Initialize under nn::pl::sharedresource::GetPlatformSharedResourceManager (first thing in nnMain). → Shared fonts requested all at once
• controller-button icons in text show as ?. → Nintendo-extension glyphs for button icons
• on a phone, GetSharedFontLoadState would report "not loaded". → 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
• 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
• 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
• 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
• 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
• a library's free rejects a pointer (CentralHeap::Free → NotNMallocPtrError). → 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
• crash in nn::ro::InitializeWithPortName. → nn::ro 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
• [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
• 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
• 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
• [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
• harmless on the build it was written for, silent memory corruption on any other. → Code inherited from another title at fixed addresses

Movies

• abort in NVIDIA's video path (NvRmChannelOpen → NvOsDrvOpen). → The SDK's 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
• 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)
• 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
• the first deferred signal crashed in InternalCriticalSectionImplByHorizon::Enter (DRAGON QUEST XI S). → 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
• 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
• decoding the end-of-stream packet gave VideoToolbox −12909 and AudioToolbox −50. → 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
• 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
• 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
• 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
• 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
• 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
• 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
• 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
• looping movie previews flash black at the end of every loop. → 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
• VP8 WebM movies play black; movie::Decoder is created with decoder type 2. → VP8 uses the same libvpx worker and output paths

Audio

• abort with Result 0x499 in audio::GetAudioRendererWorkBufferSize. → SDK 8's 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
• [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)
• 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)
• 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)
• SIGSEGV at address 0x18 in UpsamplerManager::Allocate on the render thread. → 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
• the CPU processor drops the final mix. → The final mix is taken from the DeviceSink's 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
• no sound; red audren: command 1 in the command list is malformed (magic 0 size 0). → 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
• 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
• FMOD waits for buffer release after stopping an AudioOut, hanging the game during a scene transition. → Stopping an AudioOut releases its pending buffers
• crackling on iOS only. → RemoteIO's default I/O buffer duration
• 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
• 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)
• 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
• a null read in audio::GetAudioOutBufferCount on Wwise's sink wakeup thread (sdk+0x1e7ed0, from main+0x30faae8). → 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
• SDL3's audio driver lists the input devices (AudioIn) when its audio starts. → 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
• the light limiter crashed on a null state pointer (ApplyLightLimiterEffect, sdk+0x228494). → 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

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
• 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
• 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
• 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
• GPU time reads 32 times too small when a game converts raw NVN counter timestamps itself. → 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
• 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
• 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
• 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
• 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
• "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
• 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
• 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
• 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
• 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
• 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
• the submit thread waits on the texture / sampler registry lock while a lower-priority registration thread is preempted holding it. → Registry lock priority inheritance
• 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
• 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
• 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

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
• 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
• sprites broke apart in some runs only, depending on the allocation order; buffers overlapped. → 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
• [RED] memory pool … created at retry N. → 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
• [RED] MapVirtual: non-contiguous mapping (true sparse) not implemented. → Sparse virtual pools built from separate physical pools
• 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
• 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
• 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
• the serial table grows by about 10 entries a frame (276,000 after 25,000 frames). → Dead texture serials kept in a ghost table
• FATAL NVN command memory: the game's pool is empty…. → 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
• 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
• 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)
• nvnCommandBufferFenceSync unimplemented, every SyncWait timed out at once. → Fence syncs recorded in command buffers
• FATAL submit re-entered in the first frames. → 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
• 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
• 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
• 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
• 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
• 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
• a trap during graphics initialization in SetupSurfaceInfoMemoryInside, asserting ctx.memorySize <= localmemsetupinfo.memorySize. → 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
• 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
• 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
• 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
• a movie plays black (Age of Calamity: its intro movie under the "+ Skip" prompt). → 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)
• 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
• 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
• some textures are re-uploaded every frame (several MB per frame). → 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
• 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
• a CPU-written texture stays stale after later writes; letters can be missing from a glyph cache. → Dirty-page writes missed during upload
• device / subsystem setup returns quietly and the next stage never starts. → 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
• 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
• 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
• SIGBUS in AGCDeserializedReply, address in the guest stack region. → 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
• an abort in device setup when nvnTexturePoolGetSize / nvnSamplerPoolGetSize returned 0. → Pool size getters, texture address and command memory size
• red stub lines for NVN calls. → NVN calls that were red stubs
• nvnWindowGetPresentInterval, nvnCommandBufferSetCopyImageStride missing. → 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
• 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
• glyphs render as white boxes (the font atlas is (1, 1, 1, R)). → 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
• 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
• 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
• a type mismatch when a Metal 1D texture is bound to a shader's texture2d argument. → 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
• 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
• an abort in Metal's validation: newSliceRange.length(1) must be a multiple of (6). → 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
• translucent UI (frosted text bands, button guides, dialog headers) yellow and white. → 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)
• torn digits and a background in blue steps (Rhythm Heaven Groove's latency calibration). → 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
• streamed textures read 0 (magenta on Monster Hunter Rise's title screen's clothes). → Sparse textures bound from their first mapped level
• ≈13 MB/frame leak. → 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
• 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
• a clear of, or a format-converting copy into, a texture made without render-target use is declined. → 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
• the boot aborts in Metal's pipeline validation: MTLPixelFormatDepth16Unorm is not color renderable. → 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
• no render target could get an MTLTexture (the pass skipped). → 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
• 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
• 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
• 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
• texture clear case not implemented … mask 0x1. → 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
• 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
• 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
• 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
• 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
• 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
• 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
• undefined values blended into attachments the fragment shader leaves alone. → 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
• 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
• a character drawn as a dithered silhouette inside a dithered square (DRAGON QUEST VII Reimagined's hero). → 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
• 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
• 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
• 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
• vertex attribute format … not mapped (printed once). → Vertex formats Metal lacks
• the assertion buffer index (31) must be < 31. → 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
• [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
• 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
• 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
• 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
• 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
• characters collapsed into one thin spike (vertex streams read from feedback buffers that were never written); a pass dump shows a pass of draws with a vertex shader and no fragment shader (fs=-) before the pass that reads them. → 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
• 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
• 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
• 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
• 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
• 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
• stage 0 cb5 has no uniform buffer bound. → 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
• dialog boxes with holes the size of their text, and white specks where text faded. → 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
• 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
• [RED] Downsample case not implemented: 320x176 1 samples format 70 → 80x48; a missing bloom. → 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
• DM_NVN_GPUPROF=every:1 prints no per-frame reports and fills its timestamp heap across frames. → 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
• 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
• 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
• Metal refuses the pipeline: "Fragment shader does not write to render target color(0), index(1)". → 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
• 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
• draw outside a render pass; the rest of the pass was dropped. → 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
• 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
• UNIMPL eglGetDisplay, then Break right after nv::InitializeGraphics and vi::OpenDefaultDisplay (main+0x5ed9d0). → 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
• 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
• a jump to address 0 right after glGetFloatv(0xb12) (lr=main+0x2d58c4). → 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

Shaders

• shader_split.py finds 0 shaders in a RomFS of zstd files named .zst. → Zstd files recognised by their magic
• a provisional split finds only a fraction of the shaders (3,126 of Pokémon Sword's 41,516). → BNSH entries of GFPAK archives
• the split found no shader in the game (0 shaders). → 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
• 24 shaders before the control-length fix, 1,355 after. → SPKG packages in KTGL LINKDATA
• [RED] ... PKZ version 0x10000: only 0x20000 is known stops the shader split. → 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
• 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
• 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)
• 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)
• 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
• 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
• 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)
• shaders reported missing at random, and their dumped control sections are garbage (Unity). → 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
• 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
• 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
• SPIRV-Cross can't parse the SPIR-V (nullptr exception). → 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
• 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)
• 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
• 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
• 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
• 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
• failed to create render pipeline … Cannot convert attribute …; draws missing (a pipeline that fails to build). → 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
• SPIRV-Cross threw an exception: Subgroup builtins are not available in this type of function. → 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
• 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
• 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
• 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
• 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
• 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
• 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
• [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
• primitive type 14 not implemented; patch draws skipped. → Tessellation stages are not drawn
• a vertex or compute shader reads zeros from NVN's driver segment c0. → 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
• [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
• 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
• point sprites of size 0 (Odyssey's Cap Kingdom fog never parted around Mario). → 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
• 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
• 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
• 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
• the 3D scene black, only particles and the HUD drawn; pass dump B lines all tid=0 dummy. → 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
• a storage buffer reported with cb_slot 3, which had no NVN slot. → Storage buffer addresses in the game's 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
• 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
• 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
• 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
• 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
• 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
• [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
• 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
• 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
• shaders missing from the map that no game file holds. → Built-in shaders compiled with the game's 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
• 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
• identical render pipelines compile repeatedly under different keys, lengthening startup prewarm and adding pipeline misses during play. → Pipeline keys omit unused colour state
• a vertex shader whose pairs changed was restored unpadded from cas/. → 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
• a pipeline for a vertex shader that writes render_target_array_index cannot be built. → 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
• 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
• 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

Game state

• "stuck" at a screen with one draw per frame. → Most draws are in command buffers replayed later
• menus ignore A. → 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
• the TV latency calibration ("press A when you hear the fourth beat") ignores A. → TV latency calibration's 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)
• 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)