3.5 File System Error Handling

An application must implement proper error handling to deal with fatal errors such as corrupted save data or extra data. This chapter explains error handling related to save data, extra data, direct writes to an SD Card, and data operations that use the ImageDb and SoundIO libraries. In general, follow the Function Reference Manual and the programming manuals to handle implementation-related precautions. These Guidelines primarily describe processing that applications should perform in regard to the user.

Although there are many items in this chapter that require the display of a message, the message text itself is not specified. This is because messaging can vary based on variables such as application specifications and error status. Keep the following basic points in mind when considering the content of your messaging.

  • Messaging should show only correct information to the user, and not use expressions that could lead to misunderstandings.
  • Messaging should guide users toward correct application recovery.
  • Messaging should be visible and legible.

 

Note:

Sometimes subsequent errors can occur during error handling. (For example, after a corrupted file is detected, recreation of that file could fail.) In such cases, the application must handle the error in accordance with the Function Reference Manual and programming manuals. However, there are no particular restrictions with regard to displaying errors to the user in these cases because all applications will have their own unique specifications. Handle these errors with the above three points in mind.

 

Unless explicitly stated otherwise, these guidelines apply to both card-based software and downloadable applications.

Note:

The Function Reference Manual includes examples of error handling where errors are dealt with immediately upon detection. However, depending on the specifications of the application the chance of problems in the market may be low even if errors are not handled immediately, so Nintendo does not require that applications deal with errors immediately. The handling of things like display of messages and formatting or recreating data should be timed in a way that does not inconvenience the user. However, because unexpected power loss or Game Card removal could cause the application to quit before restoring the data, Nintendo does recommend dealing with these errors as soon as possible after detection.

 

Using the nn::fs::SetSdmcEjectionFatal Function

A system feature that automatically transitions the system to a FATAL error screen (a screen with the message "The SD Card was removed") when the SD Card is removed is available with the CTR-SDK 10.x series and later.

Any application that uses this function—even a card-based application—does not need to take any further measures to comply with the recommendations regarding insertion/removal of SD Cards while the application is running, found in sections 3.5.2 Error Handling for Extra Data, 3.5.3 Mounting Archives for Writing Directly to an SD Card, and 3.5.4 Handling ImageDb Errors.

There are no particular restrictions on use of this function. Balance the lowered development and debug costs versus user experience when you consider whether to handle SD Card removal as a FATAL error.

3.5.1 Error Handling for Save Data

This section explains how to handle errors returned during save data operations.

Note:

There is no system feature on the Nintendo 3DS for initializing a Game Card's save data region. Because of this, if a card-based application is not capable of properly handling every error, then the user may be forced to send the Game Card in to customer support.

Card-based applications in particular must comply with this chapter and ensure that the users themselves can properly recover (without any negative impact on their progress in the application) from any save data problems that may occur in the market.

 

■ When detecting card-based software in the factory-default state:

If nn::fs::ResultNotFormatted is returned when mounting save data, then the save data is either in a factory-default or unformatted state. Since either way the data is unformatted, display some indication that writing is in progress if you format the data immediately. See section 3.2.3 Screen Display While Writing Data for details on how to display this.

Note:

Follow the procedures given below if you want to return the save data region to an unformatted state.

For card-based applications:

Use a debugger or other means to fill the backup device with 0xFF.

 

For downloadable applications:

Use the SaveDataFiler tool's initialization feature (under the User tab in SaveDataFiler's main screen, select the application and press the X Button).

■ When detecting an invalid format:

If nn::fs::ResultBadFormat is returned when mounting save data, then the file format is invalid. If this happens, the save data must be formatted to be used. To handle this case, have a feature to format the save data, and either transition to that feature or display a screen that guides the user to it. It is acceptable to format the save data automatically, but we recommend informing the user that formatting occurred if the data is essential for the application to proceed.

Note that this error will not occur if your application uses Card2.

■ When corrupted save data is detected:

If nn::fs::ResultVerificationFailed is returned when mounting save data, then the save data is corrupted or has been tampered with. If this happens, the save data must be formatted to be used. Process this in the same manner as described under ■ When detecting an invalid format. Note that this error can be returned when mounting even when you have enabled the automatic data redundancy feature of the CTR-SDK.

If the nn::fs::ResultVerificationFailed error is returned when operating on save data files or directories, then the file or directory for which an operation was attempted is in an invalid state. In such cases, delete the corresponding files/directories and recreate valid data. We recommend informing the user that the data was recreated if the data is essential for the application to proceed. Furthermore, when recreating data, we recommend an implementation that has no effect on uncorrupted files or directories. (When possible, only delete and recreate corrupted files and directories.)

■ When detecting bad contact with the storage media:

If the nn::fs::ResultMediaNotFound error is returned when mounting save data, then it is possible that the backup device section of the Game Card has bad contact. Depending on the degree of bad contact with the Game Card, it might be possible to launch the application but not access the save data. This might be fixed by turning off the system and reinserting the game card. There is no particular requirement regarding message display to the user in this situation.
However, the system checks whether storage media is making good contact when an application is started, and will not launch the application if it cannot make good contact with the save data.

■ When there is insufficient space available:

If the nn::fs::ResultNotEnoughSpace error is returned when creating files and directories or increasing their size, then it is possible that there is insufficient free space. However, since all save data space is reserved, Nintendo recommends using the Worksheet for Calculating the Save Data File System Capacity (included in the CTR-SDK) or some other means to avoid this error.

■ When file or directory is missing or does not exist:

If the nn::fs::ResultNotFound error is returned when operating on save data files or directories, then the save data has been formatted but the file or directory does not exist inside the save data.
It is possible to design applications in a way that reduces occurrences of this error to the minimum possible, but no matter what, this error will always occur in the following situations.

  • The save data has already been formatted when save data is initially created
  • After formatting, and while creating a file or directory (if using automatic save data redundancy, this refers to the whole period of time up until the initial commit), the application is forced to shut down for one of the following reasons:
    • POWER Button was held down
    • Removal of startup media
    • System is closed and power is turned off, in applications that permit Sleep Mode after the data is formatted but before files and directories are created

For situations like these, you must make it possible for card-based applications to properly recreate their save data, either automatically or through a user operation, even when the save data files necessary for progressing in the application are insufficient.

 

Note:

Because Nintendo 3DS save data is archived, there is no need to anticipate the possibility that individual files or directories might be deleted after saving is complete. For example, it is safe to assume that if files created later in the save process exist, then files created earlier in the save process will also have been created successfully, unless the application itself is implemented in a way that can allow earlier-created files to disappear.

Therefore—although it would be best to implement error handling for all individual files and directories during development, because of the wide range of timings at which the application might be exited—actual tests cannot monitor the order in which the application save data's various files and directories are created, so this guideline item only targets the case where all files and directories have been deleted.


 

3.5.1.1 Handling Detection of an Invalid Save Data Format

Guideline Item

Applications must format save data when an invalid save data format is detected (when the system returns an nn::fs::ResultBadFormat error).

Software to Be Tested

Card-based applications that use Card1 and create save data.

Test Method

If you are testing the behavior of an application that uses Card1:

  1. Insert a Nintendo 3DS Game Card into a PARTNER-CTR Debugger/Writer and then run either Invalidate the backup device's format (PARTNER_CTR Debugger) or The format of the Backup memory to be illegally. (PARTNER-CTR Writer).
  2. Insert the Game Card into a Nintendo 3DS system and start the application.
  3. Try to access the save data.
  4. Format the save data from within the application.
  5. Restart the application and use the save data.

If you are not testing application behavior:

Check the source code.

Pass/Fail Determination

Passes if all of the following conditions are met.

  • At least one of the following conditions is met.
    • The save data is automatically formatted at a time that does not inconvenience the user.
    • At a time that does not inconvenience the user, there is a feature that informs the user that the save data is corrupted and allows the user to format it.
  • In step 5 or in the If you are not testing application behavior steps, the formatted save data can be used properly.

3.5.1.2 Handling Detected Corruption When Mounting Save Data

Guideline Item

Applications must format save data when they detect corruption while mounting save data (when the system returns an nn::fs::ResultVerificationFailed error).

Software to Be Tested

Applications that create save data.

Test Method

If you are testing the behavior of card-based software:

  1. Insert the application's Nintendo 3DS Game Card into a PARTNER-CTR Debugger/Writer and then write specialized save data—1MbitVerificationFailed.bin or 4MbitVerificationFailed.bin, which return an nn::fs::ResultVerificationFailed error when they are mounted—to its backup memory.
    Note: These specialized save data files are located in the $(CTRSDK_ROOT)\tools\TargetTools\CTR-TS directory on the PC.
  2. Insert the Game Card into a Nintendo 3DS system and start the application.
  3. Try to access the save data.
  4. Format the save data from within the application.
  5. Restart the application and use the save data.

If you are using Card2 to test the behavior of card-based software:

  1. Load the CCI file of an application in a PARTNER-CTR Debugger unit.
  2.  Execute the following commands in order to output the file: CTRCard operationsCard emulation controlBackup area operations (CARD2)Output backup data in emulation memory to file (Debugger->File).
  3. Open the output file with a hex editor and tamper with the first 4 KB of data.
  4. In PARTNER-CTR Debugger, execute Load file data into emulation memory backup region (File->Debugger), then launch the application.
  5. Try to access the save data.
  6. Format the save data from within the application.
  7. Restart the application and use the save data.

If you are testing the behavior of a downloadable application:

  1. Insert an SD Card with the application into a computer. Open the following file on the SD Card in a hex editor and tamper with the first 4 KB of data.
    Nintendo 3DS/…/title/<ProgramID Hi32>/<ProgramID Lo32>/data/00000001.sav
  2. Insert the SD Card into a system and start the application.
  3. Try to access the save data.
  4. Format the save data from within the application.
  5. Restart the application and use the save data.

If you are not testing application behavior:

Check the source code.

Pass/Fail Determination

Passes if all of the following conditions are met.

  • At least one of the following conditions is met.
    • The save data is automatically formatted at a time that does not inconvenience the user.
    • At a time that does not inconvenience the user, there is a feature that informs the user that the save data is corrupted and allows the user to format it.
  • The application can properly use the save data after formatting.

3.5.1.3 Handling Detected Corruption When Operating on Files or Directories in Save Data

Guideline Item

Applications must delete and recreate save data files and directories upon detecting save data corruption (when the system returns an nn::fs::ResultVerificationFailed error).

Software to Be Tested

Applications that create save data without automatic data redundancy.

Test Method
  1. Use the SaveDataFiler tool to tamper with save data and cause an nn::fs::ResultVerificationFailed error to be returned during file and directory operations.
  2. Insert the Nintendo 3DS Game Card or SD Card with the altered save data into a Nintendo 3DS system and then start the application.
  3. Try to access the save data.
  4. Recreate the files and directories from the application.
  5. Restart the application and use the save data.
Pass/Fail Determination

Passes if all of the following conditions are met.

  • At least one of the following conditions is met.
    • The corrupted save data file or directory is deleted and then recreated at a time that does not inconvenience the user.
    • A feature is implemented to inform the user that the save data is corrupted at a time that does not inconvenience the user, and enable them to delete the corrupted save data files or directories and recreate them.
  • The recreated save data can be used properly in step 5.

3.5.1.4 Handling When Files or Directories Required to Progress Through the Application Are Missing from Save Data at Startup

Guideline Item

When the application detects that files or directories required to progress through the application are missing or do not exist during an attempted file or directory operation (the nn::fs::ResultNotFound error is returned), the application must recreate the relevant files or directories.

Software to Be Tested

Card-based applications that create save data.

Test Method
  1. Launch the application with its save data in the factory-default state, and complete the formatting of save data and creation of initial data.
  2. Use the SaveDataFiler tool to delete all of the save data files.
  3. Restart the application, and write to the save data.
  4. Restart the application and use the save data.
Pass/Fail Determination

Passes if all of the following conditions are met.

  • At least one of the following conditions is met.
    • The application automatically creates initial data at a time that does not inconvenience the user.
    • At a time that does not inconvenience the user, there is a feature that informs the user that the save data is corrupted and allows the user to create initial data.
  • The application can properly use the save data in step 4.

3.5.2 Error Handling for Extra Data

This section explains how to handle the various errors that can be returned during operations on extra data. For the following reasons, all sections on error handling for extra data operations are recommended items, and are not required.

  • Generally, extra data is presumed to be data that is not critical to the application.
  • The role and uses of extra data vary greatly depending on the application, and optimal error handling depends on the specifications of the application.

Many of the items in this section recommend displaying a message or otherwise using some method to notify the user that an error occurred. In cases such as the following Nintendo strongly recommends complying with the various items in this section, because in these cases displaying a message is likely to give the user important information.

  • When saving data important to the application, such as progress data
  • When accessing extra data because of an explicit user operation

On the other hand, Nintendo considers it less likely that the user will be inconvenienced if no message is displayed in cases like the following:

  • When the extra data was created by a different application and is only being loaded as bonus elements
  • When the application automatically saves minor data as extra data

Please use the content of this section as a reference and perform the optimal error handling for your application based on its specifications.

■ When the extra data archive is not found:

If the nn::fs::ResultNotFound error is returned (and the error is not nn::fs::ResultMediaNotFound), then the extra data you are attempting to mount does not exist.

Applications that write to extra data must create a new archive in compliance with section 3.3.3 User Confirmation When Creating New Extra Data.

■ When no SD Card is inserted:

If the nn::fs::ResultMediaNotFound error (which is related to the nn::fs::ResultNotFound error) is returned when mounting extra data or when operating on files/directories, then either no SD card is inserted or an empty miniSD adapter or other non-SD card is inserted.

In this case, Nintendo recommends notifying the user that the system failed to recognize the SD Card, or that no SD Card is inserted. Because downloadable applications launch from the SD Card, this error is never returned in a downloadable application.

Note:

When nn::fs::ResultMediaNotFound is returned, you can call the nn::fs::IsSdmcInserted function to differentiate between having nothing inserted in the SD Card slot and having media other than an SD Card inserted in the SD Card slot. As shown in the following examples, it is acceptable to differentiate between these two cases to display different messages.
(Example)
When an SD Card has not been inserted:
 "No SD Card inserted."
When media other than an SD Card has been inserted:
 "Cannot use the media inserted in the SD Card slot."

Note:

If the nn::fs::ResultMediaNotFound error is returned when operating on files or directories, then it is possible that the SD Card was removed while the application was running, because original mounting of the media was successful. In this case, it is acceptable to display a different message, such as "The SD Card was removed," and thereby differentiate from cases where this error occurs during mounting.

■When detecting bad contact with the SD Card:

If the nn::fs::ResultMediaAccessError (related to the nn::fs::ResultOperationDenied error) is returned when performing file or directory operations or when mounting extra data, the card in the SD Card slot is either making bad contact, or it may be broken. In this case, Nintendo recommends notifying the user that the system failed to recognize the SD Card. Reinserting may fix this issue if the problem is simply that the SD Card is making bad contact. The application can optionally inform the user of this. However, be careful not to encourage reinserting an SD Card while an application is running, as described in section 3.1.3 Access to SD Cards. One way to avoid this is to prompt the user to turn off the power before reinserting the SD card. Because downloadable applications launch from the SD Card, this error is never returned in a downloadable application.

■When detecting extra data that is corrupt or tampered-with, or when data creation has failed:

If the nn::fs::ResultVerificationFailed error or the nn::fs::ResultNotFormatted error is returned when mounting extra data, then the extra data is corrupted. In this case, Nintendo strongly recommends that the application delete and recreate the extra data, or that the application prompt the user to delete the extra data in System Settings. User consent is not required before recreating such extra data, but if your application recreates it automatically, Nintendo recommends notifying the user that the extra data has been recreated.

If the nn::fs::ResultVerificationFailed error is returned when operating on extra data files or directories, then the file or directory for which an operation was attempted is in an invalid format. In such cases, Nintendo recommends deleting that file or directory and recreating data that is valid. When recreating data, Nintendo recommends recreating the minimum possible amount of data, except in cases where several related files or directories must be recreated together in order to stay consistent. In addition, it is recommended to inform the user that data has been recreated if that data is important for application progress.


Note:

For extra data, an nn::fs::ResultNotFormatted error is mainly returned when creation of the extra data failed; this can be considered one type of data corruption. Therefore we recommend that you refer to the data as “corrupted” instead of “uninitialized” in any messages shown to the user when you recreate extra data because of an nn::fs::ResultNotFormatted error.

The following is a sample message: “Extra data is corrupted. Recreate extra data for <title name>?”

Note:

You can use the following steps to check the behavior of the application when corruption is detected while mounting extra data.

Method for Causing nn::fs::ResultVerificationFailed

  1. Insert the SD Card with the extra data into a computer. Open the following file on the SD Card in a hex editor and tamper with the first 4 KB of data.
    Nintendo 3DS/…/extdata/<StorageID Hi32>/<StorageID Lo32>/00000000/00000001
  2. Insert the SD Card into a system and start the application.
  3. Try to access the extra data.

Method for Causing nn::fs::ResultNotFormatted

  1. Insert the SD Card with the extra data into a computer. Delete the following directory or file on the SD Card.
    Nintendo 3DS/…/extdata/<StorageID Hi32>/<StorageID Lo32>/00000000 (Directory)
    Nintendo 3DS/…/extdata/<StorageID Hi32>/<StorageID Lo32>/00000000/00000001
  2. Insert the SD Card into a system and start the application.
  3. Try to access the extra data.
Note:

You can use the following steps to check the behavior of the application when corruption is detected while operating on files or directories.

Method for Causing nn::fs::ResultVerificationFailed

  1. Insert the SD Card with the extra data into a computer. Open the following file on the SD Card in a hex editor and tamper with the first 4 KB of data.
    All files except 00000001 and 00000002 in the Nintendo 3DS/…/extdata/<StorageID Hi32>/<StorageID Lo32>/00000000 directory.
  2. Insert the SD Card into a system and start the application.
  3. Try to access the extra data.

■ When detecting an invalid format:

If the nn::fs::ResultBadFormat error is returned when mounting extra data, then the SD card format is invalid or is not supported by the Nintendo 3DS system (for example, NTFS). In this case, Nintendo recommends notifying the user that the system failed to recognize the SD Card. If the card is in a format unsupported by Nintendo 3DS, the user must format the SD Card with an SD formatter, possibly by using a PC. Informing the user of this additional step is optional. Because downloadable applications launch from the SD Card, this error is never returned in a downloadable application.

■ When the SD Card is write-protected:

If the nn::fs::ResultWriteProtected error (related to the nn::fs::ResultOperationDenied error) is returned when performing a write operation that includes the creation of extra data, then the SD card is write-protected. In this case, Nintendo recommends notifying the user that the SD Card is write-protected. However, be careful not to encourage reinserting an SD Card while an application is running, as described in section 3.1.3 Access to SD Cards. One way to avoid this is to prompt the user to turn off the power and unlock the SD Card to enable writing before reinserting. Because downloadable applications cannot launch when the SD Card is write-protected, this error is never returned in a downloadable application.

 

Note:

Due to system specifications, nn::fs::ResultOperationDenied is sometimes returned instead of nn::fs::ResultWriteProtected when attempting to access a write-protected SD Card. Therefore, there is no method guaranteed to cause nn::fs::ResultWriteProtected.

■ When an SD Card operation is denied:

When mounting extra data or operating on a file or directory, an instance of nn::fs::ResultOperationDenied that is unrelated to either nn::fs::ResultWriteProtected or nn::fs::ResultMediaAccessError is sometimes returned. In this case, Nintendo recommends notifying the user that the system failed to recognize the SD Card. There are a number of possible reasons for operations to be denied, so the cause of this error cannot be determined for certain. There are several possible ways to cause this error to occur in the application, but one is to take an SD Card with extra data written to it and set the extra data files to read-only status on a PC, then try to access the extra data again from the application.

■ When there is insufficient space available:

If the nn::fs::ResultNotEnoughSpace error is returned when creating extra data or when creating file/directory on extra data, then there could be insufficient space on the SD card. In this case, Nintendo recommends notifying the user that there is not enough space available on the SD Card. Similarly, when the application attempts to save relatively large data greater than several hundred KB, Nintendo recommends using the Worksheet for Calculating the Save Data File System Capacity in the CTR-SDK to calculate and display how much space is required. In this case, because the amount of space actually required can sometimes be larger than calculated due to things like the size of SD Card clusters, Nintendo recommends phrasing such as "at least XX blocks needed." The Nintendo standard unit for displaying data sizes on screen is the "block," of 128 KB each, but you can use some other unit that fits the design of your application and makes it easier for the user to understand.


No required guideline items.

3.5.3 Mounting Archives for Writing Directly to an SD Card

Using the nn::fs::MountSdmcWriteOnly function, you can mount an archive for writing directly to an SD Card. Use the procedures described in section 3.5.2 Error Handling for Extra Data as a reference when handling any errors that are returned.

No required guideline items.

3.5.4 Handling ImageDb Errors

Although the Result values returned by each of the ImageDb functions vary slightly from the values returned when the FS library is used, most symptoms are handled as described in section 3.5.2 Error Handling for Extra Data. For sample messages, see the ImageDb Programming Manual as well.

■ When no SD Card is inserted:

An imgdb::ResultErrorNotExistStorage error is returned when an SD Card has not been inserted. For details, see ■ When no SD Card is inserted in section 3.5.2 Error Handling for Extra Data. Note, however, that the ImageDb library differentiates between a missing SD Card and inserted media other than an SD Card. For information on what to do if media other than an SD Card is inserted, see ■ When media other than an SD Card has been inserted, further down in the Handling ImageDb Errors section.

■ When the SD Card is write-protected:

An imgdb::ResultErrorWriteProtect error is returned when the SD Card is write-protected. For details, see ■ When the SD Card is write-protected in section 3.5.2 Error Handling for Extra Data.

■ When there is insufficient space available:

An imgdb::ResultErrorInsufficientStorageSpace error is returned when there isn’t enough free space on the SD Card. For details, see ■ When there is insufficient space available in section 3.5.2 Error Handling for Extra Data.

■ When the maximum number of photos have already been saved:

An imgdb::ResultErrorOverNumImages error is returned when the Nintendo 3DS photo directory already has the maximum number of photos—3000. In this case, notify the user that the maximum number of photos in the Nintendo 3DS photo directory has been reached. Rather than simply saying that there is not enough free space on the SD Card, we recommend that you make it clear that the maximum number of photos has been reached.

To check the behavior of an application when this error is detected, use the sample data contained in the ImageDb package. Copy the directories below tools/ResultErrorOverNumImages sample/Nintendo 3DS into the SD Card's root directory, then launch the application and attempt to add more photos.

■ When media other than an SD Card has been inserted:

The imgdb::ResultErrorNotAvailableStorage error is returned when media other than an SD Card has been inserted, when the SD Card has bad contact, and when the SD Card format is not supported by the Nintendo 3DS system. In this case, because the application cannot pinpoint the cause, Nintendo recommends notifying the user that the system failed to recognize the SD Card.

No required guideline items.

 


CONFIDENTIAL