Data File Troubleshooting ​

Intermediate40-60 minutesWindowsUnturned

Data files (.dat and .asset files) are the configuration backbone of every Unturned™ mod. A single syntax error in a data file can prevent an entire asset from loading, cause the engine to misinterpret a field value, or silently apply default values where custom values were intended. The engine's parser is reasonably tolerant of minor errors, but certain types of malformation will cause the parser to reject the file entirely. Understanding the parser's error tolerance and knowing how to validate data files before loading them in-game is essential for efficient mod development.

57 Studios™ has documented and validated the complete data file troubleshooting surface. This reference covers every common type of syntax error (missing braces, unquoted strings, repeated fields, wrong type values), the parser's error tolerance for each error type, the validation workflow for checking data files before in-game testing, a comprehensive diagnostic table mapping errors to symptoms and fixes, and worked examples of the most common mistakes that new mod authors make.

Data file syntax error displayed in the Unturned client log

Documentation source: This article references the official Smartly Dressed Games modding documentation for the Data File Format chapter, combined with the 57 Studios cohort's empirical testing of parser behavior across 200+ deliberately malformed test files. Error tolerance limits documented below are based on empirical testing, not official documentation.

Who this article is for ​

This troubleshooting reference is written for Unturned™ mod authors who are encountering errors when the game attempts to load their .dat or .asset files. If you are new to the data file format, start with Data File Format Reference before returning here.

What you will learn ​

  • The common syntax errors in .dat and .asset files and their symptoms
  • The parser's error tolerance for each error type
  • How to validate data files before loading them in-game
  • The diagnostic table mapping specific error messages to concrete fixes
  • Worked examples of the most common data file mistakes and their corrections

How the parser processes data files ​

The Unturned™ data file parser reads each .dat and .asset file line by line. Each line is expected to be a key-value pair separated by a space. Keys and values can optionally be enclosed in quotation marks. Dictionaries are opened with { on a new line and closed with } on a new line. Arrays are opened with [ on a new line and closed with ] on a new line.

As shown in the flowchart above, the parser attempts to continue after recoverable errors. Fatal errors cause the entire file to be rejected.

Common syntax errors ​

Missing closing brace ​

The most common data file syntax error is a missing closing brace } on a dictionary or a missing closing bracket ] on an array. When a { is opened on a new line, the matching } must appear somewhere later in the file.

Error example:

object1
{
    key value

In this example, object1 opens a dictionary with { but never closes it with }. The parser reports an error at the end of the file indicating an unclosed dictionary.

Fix: Add the matching }:

object1
{
    key value
}

Unquoted string with spaces ​

When a value contains spaces and is not enclosed in quotation marks, the parser reads only the first word as the value and attempts to read the remaining words as additional keys or values.

Error example:

Name Survival Rifle

The parser reads Survival as the value of Name and then interprets Rifle as a new key with no value. This produces a parse warning and both keys are stored incorrectly.

Fix: Enclose the value in quotation marks:

Name "Survival Rifle"

Repeated fields ​

When the same key appears twice in the same dictionary, the later occurrence overwrites the earlier one. The parser does not report an error for repeated fields, but the earlier value is silently discarded.

Error example:

Name SurvivalRifle
Name SecondaryName

Only SecondaryName is retained as the value of Name. The first occurrence is discarded.

Fix: Ensure each key appears only once within its dictionary scope.

Wrong value type ​

When a field expects a specific value type (such as a number for ID or a boolean for Bypass_ID_Limit) and receives a different type, the parser may skip the field and use the default value.

Error example:

ID "Five thousand"

The ID field expects a uint16 numeric value. The string "Five thousand" cannot be parsed as a number, so the field is skipped and the default ID of 0 is used.

Fix: Use the correct type:

ID 5000

Incorrect dictionary or array opening ​

A dictionary or array must be opened on a new line after the key. Opening on the same line is not supported because it would break backwards compatibility with older .dat files.

Error example:

object1 {
    key value
}

Fix: Place the opening brace on a new line:

object1
{
    key value
}

Parser error tolerance ​

The parser's error tolerance varies by error type. The table below summarizes whether the parser can recover from each error type.

Error typeParser recovers?Effect on assetLog level
Missing closing brace }NoEntire file rejectedError
Missing closing bracket ]NoEntire file rejectedError
Unquoted string with spacesPartialIncorrect parsing; values may be misinterpretedWarning
Repeated field (same key)YesLast value wins; earlier value lostNone
Wrong value typePartialField uses default value; rest of file processesWarning
Opening brace on same lineYes (older files)Deprecated but toleratedNone
Unknown field nameYesField ignored; file continuesNone
Missing value after keyPartialKey stored with empty valueWarning
Invalid comment syntaxYesComment not recognized; may be parsed as key-valueNone

The 57 Studios cohort recommendation is to fix all errors and warnings, even those the parser can tolerate. A warning today may become an error in a future version of the engine.

How to validate .dat files before loading in-game ​

The most efficient way to validate data files is to use the -ValidateAssets command-line flag. This flag enables comprehensive validation that checks every .dat and .asset file for syntax errors, missing references, and other issues.

Validation workflow ​

  1. Open the Unturned™ launch options (in Steam: Right-click Unturned -> Properties -> General -> Launch Options).
  2. Add -ValidateAssets to the launch options.
  3. Launch the game and load a map with the mod active.
  4. Press Escape and check the Asset Errors menu for any reported errors.
  5. Review each error, note the file path and line number, and fix the issue.
  6. Repeat steps 3-5 until no errors remain.

Manual validation ​

For quick syntax checks without launching the game, the following manual checks can catch most common errors:

  • Verify that every { has a matching } and every [ has a matching ].
  • Verify that multi-word values are enclosed in quotation marks.
  • Verify that keys are unique within each dictionary scope.
  • Verify that numeric fields contain numeric values, not text.
  • Verify that boolean fields use true or false (not yes or no or 1/0).

Diagnostic table ​

Error message or symptomMost likely causeFix
"Parser error at line X: Unclosed dictionary"Missing closing } for a dictionary opened at or before line XAdd the matching } after the dictionary's contents
"Parser error at line X: Unclosed array"Missing closing ] for an arrayAdd the matching ]
Field shows default value instead of the specified valueWrong value type (string for number, etc.)Correct the value type to match the field's expected type
Item shows internal name instead of display nameName value was not quoted and only the first word was readQuote the Name value: Name "Display Name"
Item has unexpected statsA numeric field was set to a string valueVerify numeric fields contain numbers only
Some fields are missing from the assetRepeated key names caused later values to overwrite earlier onesEnsure each key appears only once per dictionary
File is completely ignored by the engineFatal syntax error (unclosed brace, unclosed bracket)Fix the syntax error
Comment not workingComment line does not start with // at the beginning of the lineAdd // at the start of the comment line
Array elements not being readArray opening [ is on the same line as the keyMove the [ to a new line

Worked examples of common mistakes ​

Mistake 1: Missing closing brace on an asset file ​

Broken file:

GUID a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
Type Item
ID 5000

The file has no closing for the root dictionary. The parser reaches the end of the file without finding the implicit closing.

Fixed file:

GUID a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
Type Item
ID 5000

The root dictionary in a .dat file is implicit and does not require explicit braces. This file is valid.

Mistake 2: Unquoted multi-word Name value ​

Broken file:

GUID a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
Type Item
ID 5000
Name Survival Rifle

The parser reads Survival as the Name value and Rifle as a new key. A parse warning is logged.

Fixed file:

GUID a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
Type Item
ID 5000
Name "Survival Rifle"

Mistake 3: Opening brace on the same line ​

Broken file:

object1 {
    key value
}

This pattern is deprecated and may not work correctly with all asset types.

Fixed file:

object1
{
    key value
}

Mistake 4: Wrong value type for ID ​

Broken file:

ID 50,000

The comma causes the parser to fail to read the value as a number.

Fixed file:

ID 50000

Mistake 5: Space in a field name ​

Broken file:

My Key value

The parser reads My as the key and Key as the value, and value as an additional leftover token.

Fixed file:

My_Key value

FAQ ​

How do I find the exact line of a parser error? ​

The error message in the log file includes the line number where the parser encountered the problem. For unclosed dictionaries or arrays, the error is reported at the end of the file (the parser discovers the missing closure when it reaches the end without finding it). The line number points to the line where the opening { or [ is located.

Can I use tabs instead of spaces in data files? ​

Tabs and spaces are both accepted by the parser. The 57 Studios cohort recommendation is to use spaces consistently (2-space or 4-space indentation) for readability.

Can I have empty lines in a .dat file? ​

Yes. Empty lines are ignored by the parser. They can be used to separate sections of the file for readability.

Can I use inline comments after a key-value pair? ​

Inline comments are only supported when the value is enclosed in quotation marks. The comment must appear after the closing quote:

Name "Survival Rifle" // This is an inline comment

If the value is not quoted, the // is treated as part of the value, not as a comment.

Does the parser care about capitalization in field names? ​

Keys are case-insensitive. Name, name, and NAME are all treated as the same key. The last occurrence of a repeated key overwrites the earlier ones regardless of capitalization.

Can a .dat file have no keys at all? ​

Yes. An empty .dat file is valid. The parser processes it without errors. An empty file produces an asset with no fields, which will use all default values. This is occasionally useful for placeholder or marker assets.

How do I include a literal quotation mark in a value? ​

Escape the quotation mark with a backslash: \". For example, Name "The \"Ultimate\" Rifle" produces the display name The "Ultimate" Rifle.

How do I include a backslash character in a value? ​

Use a double backslash: \\. For example, IconPath "Items\\Weapons\\Rifle.png" produces the path Items\Weapons\Rifle.png.

What happens if I use a value that is too large for a numeric field? ​

The parser clamps the value to the field's valid range. For a uint8 field (0-255), a value of 300 is clamped to 255. A value of -5 is clamped to 0. The clamping is silent; no warning is logged.

How do I know which fields a specific asset type supports? ​

The field set is defined by the asset's C# class in the Unturned™ source code. The official SDG modding documentation lists the supported fields for each asset type. The 57 Studios documentation covers field sets for the most common asset types.

Best practices ​

  • Validate every .dat and .asset file with -ValidateAssets before publishing
  • Use quotation marks around all multi-word values
  • Keep keys unique within each dictionary scope
  • Use numeric values for numeric fields
  • Place opening braces and brackets on their own lines
  • Use consistent indentation (spaces, not tabs) for nested structures
  • Add comments with // at the start of dedicated comment lines
  • Test each file after editing by loading it in-game before the next edit
  • Keep a backup of known-good versions of data files for comparison

Appendix A: Quick-reference syntax validator checklist ​

Use this checklist when reviewing a .dat or .asset file for syntax errors.

  • [ ] All { characters have a matching } character
  • [ ] All [ characters have a matching ] character
  • [ ] All multi-word values are enclosed in quotation marks
  • [ ] No key appears more than once in the same dictionary
  • [ ] Numeric fields contain only numeric characters
  • [ ] Boolean fields use true or false
  • [ ] Opening { and [ are on their own lines
  • [ ] Comment lines start with // at the beginning of the line
  • [ ] No tabs are used (spaces only for indentation)
  • [ ] File encoding is UTF-8 without BOM

Appendix B: Parser error message reference ​

Error messageMeaningAction
Parser error at line <N>: Unclosed dictionaryA { at or before line N has no matching }Add the closing }
Parser error at line <N>: Unclosed arrayA [ at or before line N has no matching ]Add the closing ]
Parser error at line <N>: Invalid key-value pairA line could not be parsed as key-value, brace, or bracketCheck for unquoted spaces in values
Parser error: Unexpected tokenThe parser encountered a character it did not expectReview the file around the reported location
Warning: Value truncated for field <field>A numeric value exceeded the field's rangeReduce the value to fit within the range

Appendix C: External references ​

Advanced considerations ​

Cross-referencing syntax errors across language files ​

When a mod includes multiple language localization files, a syntax error in one language file does not affect the others. The parser processes each file independently. However, the localization system will fall back to English if the player's language file is rejected due to a syntax error. The 57 Studios cohort recommendation is to validate all language files with the same rigor as the primary .dat files.

Syntax validation in automated build pipelines ​

Mod teams that use automated build pipelines should include a validation step that checks all .dat and .asset files for basic syntax correctness before the build is finalized. A simple script can check for matched braces and brackets, verify that multi-word values are quoted, and report any issues found. The 57 Studios cohort recommendation is to make the syntax validation a mandatory step in the build pipeline that blocks the build if any errors are found.

Data file encoding troubleshooting ​

The file encoding of .dat and .asset files can cause errors that are not syntax-related. The parser expects UTF-8 encoding without a byte order mark (BOM).

Encoding issueSymptomFix
UTF-8 with BOMFirst key may not be recognized; "invalid key-value pair" at line 1Re-save as UTF-8 without BOM
UTF-16Entire file appears as garbled charactersRe-save as UTF-8 without BOM
ANSI/Latin-1Accented characters display incorrectlyRe-save as UTF-8 without BOM
CRLF vs LFNo difference; both line ending styles are acceptedUse whichever is standard for the editor
Mixed encodingInconsistent character displayConvert all files to the same encoding

The 57 Studios cohort recommendation is to configure the text editor to always save .dat and .asset files as UTF-8 without BOM. Most modern text editors (Notepad++, VS Code) support this as a configurable default.

Data file structure validation patterns ​

The following patterns validate common data file structures.

Dictionary structure validation ​

root
{
    child1
    {
        key1 value1
    }
    child2
    {
        key2 value2
    }
}

Each { matches a } further down. The depth is visually tracked by indentation.

Array structure validation ​

items
[
    {
        name "Item One"
        weight 10
    }
    {
        name "Item Two"
        weight 20
    }
]

Each [ matches a ] further down. Each { within the array has a matching }.

Authoring checklist ​

Before publishing a mod, confirm the following data-file-related items:

  • [ ] All .dat and .asset files parse without errors under -ValidateAssets
  • [ ] All braces and brackets are properly matched
  • [ ] All multi-word values are in quotation marks
  • [ ] No duplicate keys exist in any dictionary
  • [ ] Numeric fields contain numeric values within the valid range
  • [ ] Boolean fields use true or false notation
  • [ ] Opening braces and brackets are on their own lines
  • [ ] Comment syntax is correct (// at line start)
  • [ ] Encoding is UTF-8 without BOM
  • [ ] Inline comments are only used after quoted values

The 57 Studios documentation team maintains this reference to help mod authors diagnose and fix data file errors efficiently. The techniques described here apply to all .dat and .asset file types across all Unturned modding disciplines.

Document history ​

VersionDateAuthorNotes
1.02026-07-2657 StudiosInitial publication. Complete data file troubleshooting reference with syntax error guide, parser tolerance, diagnostic table, worked examples, and validation workflow.

Cross-references ​

57 Studios logo with slogan

Beginner-friendly guides for Unturned modding, tools, publishing, server operations, and troubleshooting.

Learn

Getting StartedSteam SetupInstalling Unturned

Explore

ItemsSelf-HostingTroubleshootingHome

Built for Unturned creators, server staff, and 57 Studios™ contributors.

Copyright © 57 Studios™. All rights reserved. 57 Studios™, its branding, guides, and associated original content are protected by applicable copyright and trademark law.