Troubleshooting

Start here when a setting does not appear in the game or does not behave the way you declared it. Gears skips a bad setting rather than failing the whole file, so most problems show up only as a line in the game log.

Read the log

Every Gears line starts with [Gears], and most carry a second tag naming the component that wrote it:

[Gears] [XmlSettingsParserV2] Slider 'fov' has no defaultValue; defaultValue is required, skipping.

Search the log for [Gears]. On Windows, the log files are in %APPDATA%\7DaysToDie\logs. In the game, press F1 to open the console, then press the button in its top-right corner to open the log folder. You can also read the lines in the console itself.

Some lines are debug-only and hidden by default: the "does not contain a ModSettings.xml" notice, the per-setting world values at world start, and the inline modsetting() expansions. Turn them on with the console command:

gears debug on

Running gears debug on its own toggles the setting. The argument may be on, off, true, false, 1 or 0, in any case. The command works in the main menu as well as in a world.

What each log tag reports

An InvalidOperationException at startup, rather than a log line, means a [SettingParser] or [SettingFormatter] method has the wrong signature. The message spells out the signature Gears expects.

Match a symptom to its cause

My mod is in the Mods menu but has no Settings tab. The whole file was rejected. Look for [ModSettingsFromXml]. The usual causes are a root with no version="2", which means a V1 file, a file that is not at the mod root beside ModInfo.xml, or XML that does not parse.

One setting is missing. Look for [XmlSettingsParserV2] lines naming it. In rough order of likelihood:

1. No defaultValue.
2. No type, or a misspelled or unknown one. Name an enum declared inside a class as MyClass+MyEnum, not MyClass.MyEnum. See Name an enum declared inside a class.
3. A string or bool on a Slider. Sliders take int and float only.
4. A type that resolves but has no setting implementation, such as double, or a custom struct with only a parser registered.
5. A Color or Binding under <World>. Gears drops these without a log line.
6. A setting placed directly under <Tab> instead of inside a <Category>. Also silent.
7. Another setting with the same name earlier in the same <Category> element, or its whole category repeating a category name earlier in the same <Tab> element. Gears drops the second one without a log line. See How duplicate names merge.

A selector shows no values. It is not an enum selector and declares neither <List> nor <Incremental>. Or one entry in allowedValues did not parse, which drops the whole list. Or <Incremental> had a bad bound, a zero increment, or a minValue above maxValue. Or the selector is a string with an <Incremental>.

A selector shows the wrong set of values. It declares both <List> and <Incremental>. Gears applies the range last, so the range wins.

A switch shows False and True instead of my labels. <Buttons> needs both left and right, and both must parse. With one missing, Gears applies neither. For a bool switch, add a <LocalizationPrefix> and localize <prefix>True and <prefix>False.

Text shows as a raw key such as myModHudScale. The key is missing from your Config/Localization.csv, or its row lacks the UsedInMainMenu mark. See Localize Your Settings.

The player's saved value comes back as the default after I renamed something. Gears keys saved values by tab, category and setting name. Renaming any of them orphans the saved value, and [SavedModSettingsFromXml] says which one.

My world settings never load while I am testing in the prefab editor. Gears skips world settings entirely for the worlds named Empty and Playtesting. It writes no WorldModSettings.xml and never calls OnWorldSettingsLoaded. Test in a real world.

After a world reloads, one world setting is back at its default and another has its value. The two settings share a name in different world categories. Gears restores saved world values by name alone, into the first setting with that name, so the second one never gets its value back. A world setting's name must be unique across all of a mod's world categories, not only within one.

My IGearsModApi callbacks never run. The class must be public, concrete and non-generic, with a public parameterless constructor, in an assembly your mod lists. Look for [GearsMod] warnings. Gears also does not run OnWorldSettingsLoaded for a mod with no world settings.

I see a TypeLoadException or an "outdated GearsAPI" line. Your mod was compiled against a different GearsAPI.dll than the one Gears is running. Rebuild against the current one.

My listener never runs at startup, only when the player changes the setting. Binding subscribes a listener; it never calls one. Add includeInSync: true to the attribute and call SyncSettingsToClass after BindSettingsClass. See Sync settings to a class.

My [SettingOnValueChanged] on a world path never runs at all. A world setting raises no OnValueChanged, so that listener is invoke-only: it needs includeInSync: true and a SyncSettingsToClass call, or nothing will ever call it. Gears does not warn about this. See [SettingOnValueChanged] on a world path.

SyncSettingsToClass logs "has not been bound". You called it for a type no BindSettingsClass ever saw — check for a typo in the typeof(...), or a missing bind.

Gears says a class "was bound with BindSettingsClass … but SyncSettingsToClass … was not called". The class has a listener written with includeInSync: true, so it asked for the values Gears just loaded, and nothing called SyncSettingsToClass for it in that callback. Add the call to OnGlobalSettingsLoaded, or to OnWorldSettingsLoaded for a world class — that one fires again on every world load and rejoin, and each load needs its own sync. See Gears warns when the sync is missing.

modsetting() returns an empty string. The setting is a Binding, which holds no value. Every other failure is an error, not an empty string.

modsetting() inline in an attribute leaves the literal text in place, or the game logs parsing errors. Gears is not installed for that player, so nothing expands the call. Guard the patch with mod_loaded('Gears'). See Read Settings in XML Patches.