How do I capture crash logs on Nintendo Switch during development?

During development, the Nintendo Switch SDEV and EDEV development kits provide crash log output through the Target Manager application. When a crash occurs, the NX crash reporter generates a dump file containing the exception type, register states, and a raw stack trace. You can retrieve these logs over USB or network connection using the Target Manager, then symbolicate them with your ELF debug symbols using the NX-specific addr2line tool provided in the SDK. For retail crash data, Nintendo collects crash reports through their backend and makes them available on the Nintendo Developer Portal with a delay of 24 to 48 hours.

What are the most common Switch-specific bugs that do not appear on other platforms?

The most common Switch-specific bugs relate to the hardware differences between docked and handheld modes. These include resolution scaling artifacts when switching between 1080p docked and 720p handheld, thermal throttling causing frame rate drops during intensive scenes in handheld mode, Joy-Con analog stick drift registering phantom input, touch screen input conflicts with controller input in handheld mode, and memory pressure crashes because the Switch has only 4 GB of shared RAM. Sleep and resume bugs are also very common, where the game state becomes corrupted or network connections silently die after the console wakes from sleep mode.

Should I file separate bug reports for docked mode and handheld mode issues?

Yes, you should file separate reports because the reproduction conditions and fixes are often completely different. A frame rate bug in handheld mode might be caused by thermal throttling and fixed by reducing shader complexity, while the same visual symptom in docked mode might be caused by resolution scaling and fixed by adjusting the render pipeline. Use a custom field or label like 'switch-mode: docked' or 'switch-mode: handheld' to filter and track these separately. If a bug truly affects both modes identically, you can link the reports or note it in a single report, but default to separate reports when in doubt.

How to Track Bugs on Nintendo Switch Games

Quick answer: During development, the Nintendo Switch SDEV and EDEV development kits provide crash log output through the Target Manager application. When a crash occurs, the NX crash reporter generates a dump file containing the exception type, register states, and a raw stack trace.

Learning how to track bugs on Nintendo switch games is a common challenge for game developers. The Nintendo Switch is one of the most rewarding and most challenging platforms to ship a game on. Its hybrid nature means your game must work in docked mode at 1080p, in handheld mode at 720p with reduced thermals, in tabletop mode with detached Joy-Cons, and gracefully survive sleep/wake cycles that can happen at any moment. Each of these configurations introduces a unique class of bugs that simply do not exist on other platforms. This guide covers how to organize your bug tracking to handle all of them.

The Dual-Mode Problem

The most fundamental challenge of Switch development is that you are effectively shipping two configurations of your game on one device. In docked mode, the Switch GPU runs at higher clock speeds and outputs at 1080p. In handheld mode, the GPU clocks down to save battery and reduce heat, the screen is 720p, and the form factor changes the control ergonomics entirely.

This means many bugs are mode-specific. A rendering artifact might only appear at the lower handheld resolution because your dynamic resolution scaling has a rounding error at 720p. A performance hitch might only trigger in handheld mode because the GPU cannot sustain the same draw call count at lower clocks. A control issue might only appear in handheld mode because the Joy-Con analog sticks have less travel than a Pro Controller.

Your bug tracking system must account for this. Every Switch bug report should include a play mode field that captures whether the issue was observed in docked, handheld, or tabletop configuration. Without this, you will waste hours trying to reproduce a bug in the wrong mode.

# Recommended custom fields for Switch bug reports
Platform:        Nintendo Switch
Play Mode:       Docked | Handheld | Tabletop
Controller:      Joy-Con Attached | Joy-Con Detached | Pro Controller
Firmware:        18.0.1
Dev Kit Type:    SDEV | EDEV | Retail
After Sleep:     Yes | No
Thermal State:   Normal | Throttled

Joy-Con Drift and Input Edge Cases

Joy-Con analog stick drift is not just a player complaint. It is a real hardware condition that your game must handle gracefully, and that your QA team must test for explicitly. Drift manifests as small, constant input on one or both axes when the stick is at rest. The magnitude varies from nearly imperceptible to significant enough to move a character or scroll a menu.

The bugs that emerge from drift are subtle. A menu cursor that slowly scrolls on its own. A character that moves when the player is not touching the stick. A camera that rotates slowly during cutscenes. An aim reticle that cannot hold steady. These are all gameplay bugs caused by a hardware condition, and they need to be tracked as such.

Apply a dead zone. Every game should implement an analog stick dead zone, but the appropriate size depends on your game. A first-person game needs a smaller dead zone for precise aiming, while a menu-heavy RPG can use a larger one. Test with multiple Joy-Con units of different ages, because drift severity varies by wear.

Test the full input matrix. The Switch supports an unusual number of controller configurations: two Joy-Cons attached to the console, two Joy-Cons in a grip, two Joy-Cons held individually (one per hand), a single Joy-Con held sideways for multiplayer, a Pro Controller, and various third-party controllers. Each configuration has different button mappings and analog stick behavior. Your bug tracker should capture which configuration was in use when a bug was found.

Input bugs on Switch also include touch screen interactions. In handheld mode, the 6.2-inch touch screen is active, and players may tap it intentionally or accidentally. If your game supports touch input, you need to test for conflicts between touch and controller input happening simultaneously. If your game does not support touch, you need to verify that accidental touches are properly ignored.

Thermal Throttling and Performance Bugs

The Switch has a passive cooling system in handheld mode (the fan is present but runs at reduced speed) and active cooling in docked mode. This means that in handheld mode, extended play sessions cause the SoC temperature to rise, which triggers thermal throttling. The GPU and CPU clocks reduce further, dropping performance below even the normal handheld baseline.

Thermal throttling bugs are insidious because they do not appear during short test sessions. A QA tester who picks up the Switch, plays for ten minutes, and puts it down will never see them. They only appear after 30 to 60 minutes of continuous play in handheld mode, especially in graphically intensive scenes.

Thermal soak testing should be a standard part of your Switch QA process. Run your most demanding scenes in handheld mode for at least 45 minutes and monitor frame rates. The bugs you find will typically be frame rate drops below your target, audio stuttering caused by the CPU being unable to mix audio in time, and in severe cases, the system forcing a lower resolution that your dynamic resolution scaler was not designed to handle.

When filing thermal bugs, include the approximate play duration before the issue appeared and whether the console felt hot to the touch. A custom field for thermal state (Normal or Throttled) helps you filter these bugs from cold-start bugs that have different root causes.

NX Crash Logs and Symbolication

When your game crashes on a Switch development kit, the system generates a crash dump that you can retrieve through Nintendo's Target Manager application. The crash dump contains the exception type (typically a data abort, prefetch abort, or undefined instruction), register values, and a raw stack trace with addresses.

To make sense of the stack trace, you need to symbolicate it using the ELF file from your build. Nintendo's SDK includes an addr2line variant that maps addresses back to source file and line number. The process looks like this:

# Retrieve crash dump from dev kit via Target Manager
# File: crash_dump_2026-03-24_001.bin

# Extract the faulting address and stack from the dump
nx-crash-parse crash_dump_2026-03-24_001.bin > stack.txt

# Symbolicate with your debug ELF
aarch64-none-elf-addr2line -e MyGame.nss.elf -f -C 0x00712A4C
# Output: InventoryManager::AddItem(ItemData const&)
#         src/inventory/inventory_manager.cpp:247

# Symbolicate the full stack
cat stack.txt | while read addr; do
  aarch64-none-elf-addr2line -e MyGame.nss.elf -f -C $addr
done

For retail builds, Nintendo collects crash data from players and makes it available on the Nintendo Developer Portal. There is a delay of one to two days before retail crash data appears. The portal shows crash counts grouped by a hash of the crash location, along with firmware version and game version breakdowns. You can download individual crash dumps for local analysis.

Upload your symbols. Nintendo's portal supports symbol upload so that stack traces are automatically symbolicated in the web view. Make sure your CI pipeline uploads the debug symbols for every build you submit to Nintendo. Without symbols, you are left with raw addresses that require manual symbolication every time you investigate a crash.

Sleep and Wake Bugs

The Switch enters sleep mode frequently. Players press the power button, close the lid, or the system auto-sleeps after a timeout. When the system wakes, your game is expected to resume seamlessly. In practice, sleep/wake is one of the most common sources of bugs on Switch.

The issues fall into several categories:

Network disconnection. All network connections are dropped during sleep. If your game uses online features, it must detect the disconnection on wake and reconnect gracefully. A common bug is that the game silently assumes the network is still active and fails on the next API call, sometimes minutes after waking.

Audio state corruption. Audio hardware is powered down during sleep. On wake, audio streams that were playing need to be restarted. Bugs include sounds playing at the wrong position, music restarting from the beginning instead of resuming, and audio channels being permanently silent until the game is restarted.

Timer and animation drift. If your game uses wall-clock time for any logic (animation timers, cooldown timers, day/night cycles), a sleep of several hours causes a massive delta time on the first frame after wake. Without clamping, this can launch physics objects into space, skip entire animation sequences, or advance time-based systems past their intended bounds.

Controller reconnection. Wirelessly connected controllers may not reconnect immediately after wake. Your game should handle the case where no controller is connected for several seconds after resume without crashing or softlocking.

Every one of these bugs should be tagged with an After Sleep: Yes field so you can see the full scope of sleep/wake issues at a glance. Include the approximate sleep duration in the bug description, as some issues only appear after long sleeps (hours) while others appear after any sleep.

Memory Pressure and the 4 GB Constraint

The Switch has 4 GB of RAM shared between the system and the game. The system reserves a portion, leaving your game with roughly 3.2 to 3.5 GB depending on system features in use. If your game also ships on PC or other consoles with 8 to 16 GB of RAM, you are likely using more memory than the Switch can provide.

Memory-related bugs on Switch include out-of-memory crashes, texture streaming failures where textures stay at their lowest mipmap, and progressive performance degradation as memory fragmentation increases over a long play session. These bugs are difficult to reproduce reliably because they depend on the exact allocation and deallocation history of a particular session.

When tracking memory bugs, include the approximate play duration, the scene or level, and any specific actions that preceded the issue (loading a new level, opening a menu with many items, spawning many enemies). If you have access to the Switch memory profiler output, attach it to the bug report. A crash that happens after 90 minutes of play in a specific level with specific actions is vastly more actionable than a crash that happens sometimes.

Organizing Reports by Platform Variant

If your game ships on Switch alongside PC, PlayStation, and Xbox, you need a clear organizational strategy to separate Switch-specific bugs from cross-platform issues. The recommended approach is a combination of labels and custom fields:

Platform label. Every bug gets a platform label (Switch, PC, PS5, Xbox). Bugs that affect multiple platforms get multiple labels. This is your primary filter.

Switch-specific fields. Only shown when the Switch label is applied. These include play mode, controller type, thermal state, after sleep, and firmware version. These fields are irrelevant for other platforms and should not clutter the form for PC or console bugs.

Lotcheck compliance tag. Nintendo's Lotcheck process has a specific set of requirements your game must pass. Bugs that could cause a Lotcheck failure should be tagged so they can be prioritized. Common Lotcheck-related bugs include improper handling of account switching, failing to pause when the HOME button is pressed, and not meeting the minimum frame rate requirement.

"A bug on Switch is not the same bug on PC, even if the symptoms look identical. The hardware context changes everything about the root cause and the fix."

Integrating with Bugnet

Bugnet supports custom fields per project, which makes it straightforward to set up Switch-specific tracking. Create custom fields for play mode, controller type, and thermal state, then configure a bug report template for your Switch project that includes these fields by default. When your QA team submits a bug from a Switch dev kit, the template ensures all the platform-specific metadata is captured automatically.

For crash data, you can push symbolicated crash dumps from your Switch build pipeline into Bugnet via the API. Each crash becomes a bug report with the stack trace, device metadata, and firmware version attached. Bugnet groups duplicate crashes automatically, so you see one entry per unique crash with a count of how many times it occurred.