Troubleshooting FAQ

Troubleshooting & FAQ

This page covers common issues encountered when modding Civilization VII and their solutions.

Quick Diagnostics

Before diving into specific issues, check these first:

1. Check Database.log - Located at %LOCALAPPDATA%\Firaxis Games\Sid Meier's Civilization VII\Logs\Database.log
2. Enable debugging - Set EnableDebugPanels 1 in AppOptions.txt
3. Validate XML - Use an XML validator to check for syntax errors
4. Start a new game - Some changes require a fresh save

---

Mod Not Loading

Mod doesn't appear in Additional Content

Cause	Solution
Wrong folder location	Place mod in %LOCALAPPDATA%\Firaxis Games\Sid Meier's Civilization VII\Mods\
Missing .modinfo file	Every mod folder needs a modname.modinfo file
Invalid XML syntax	Check for unclosed tags, missing quotes, or encoding issues
Wrong xmlns	Use xmlns="ModInfo" in the Mod element

Mod appears but content isn't loading

Cause	Solution
Wrong scope	Use scope="game" for gameplay, scope="shell" for menus
Criteria not met	Check ActionCriteria - is the age correct?
File paths wrong	Paths are relative to mod folder, case-sensitive
Missing file extension	Include .xml or .sql in Item paths

Example of correct structure:

<ActionGroups>
    <ActionGroup id="my-content" scope="game" criteria="my-criteria">
        <Actions>
            <UpdateDatabase>
                <Item>data/changes.xml</Item>  <!-- Correct -->
            </UpdateDatabase>
        </Actions>
    </ActionGroup>
</ActionGroups>

---

Content Issues

Unit/Building/Civ doesn't appear in game

Cause	Solution
Missing Types entry	Register in Types table with correct Kind
No tech unlock	Add ProgressionTreeNodeUnlocks entry
Wrong age	Check ActionCriteria matches the age you're playing
Missing shell scope	Civs/Leaders need both shell and game scope

Checklist for new content:

• Type registered in Types table
• Main definition table populated (Units, Civilizations, etc.)
• Localization text added
• Tech/civic unlock configured
• ActionCriteria matches target age

Modifier not working

Cause	Solution
Wrong ModifierId	Ensure ModifierId matches exactly (case-sensitive)
Missing EntityModifier link	Link via TraitModifiers, TraditionModifiers, etc.
Requirements not met	Check OwnerRequirementSetId and SubjectRequirementSetId
Wrong collection	Verify collection targets the right entities

Common modifier linking tables:

<TraitModifiers>
    <Row TraitType="TRAIT_MY_ABILITY" ModifierId="MY_MODIFIER"/>
</TraitModifiers>

<TraditionModifiers>
    <Row TraditionType="TRADITION_MY_POLICY" ModifierId="MY_MODIFIER"/>
</TraditionModifiers>

<UnitAbilityModifiers>
    <Row UnitAbilityType="ABILITY_MY_ABILITY" ModifierId="MY_MODIFIER"/>
</UnitAbilityModifiers>

<ConstructibleModifiers>
    <Row ConstructibleType="BUILDING_MY_BUILDING" ModifierId="MY_MODIFIER"/>
</ConstructibleModifiers>

Text not showing (displays LOC_ key)

Cause	Solution
Missing localization	Add entry to LocalizedText table
Wrong Language	Use Language="en_US" for English
Tag mismatch	LOC_ key must match exactly (case-sensitive)
UpdateText missing	Add <UpdateText> action in modinfo

Correct localization format:

<LocalizedText>
    <Row Tag="LOC_MY_TEXT_KEY" Language="en_US">
        <Text>My text content here</Text>
    </Row>
</LocalizedText>

Icon not showing

Cause	Solution
Wrong path	Use fs://game/{mod-id}/{path} format
Missing atlas	Define IconTextureAtlases entries
Wrong size	Create 50px and 38px versions
UpdateIcons missing	Add <UpdateIcons> action in modinfo

---

Age System Issues

Content only works in one age

This is expected behavior. Add separate ActionGroups for each age:

<ActionCriteria>
    <Criteria id="antiquity">
        <AgeInUse>AGE_ANTIQUITY</AgeInUse>
    </Criteria>
    <Criteria id="exploration">
        <AgeInUse>AGE_EXPLORATION</AgeInUse>
    </Criteria>
    <Criteria id="modern">
        <AgeInUse>AGE_MODERN</AgeInUse>
    </Criteria>
</ActionCriteria>

Content disappears after age transition

Add the AGELESS tag to make content persist:

<TypeTags>
    <Row Type="UNIT_MY_UNIT" Tag="AGELESS"/>
</TypeTags>

Civilization not appearing in game setup

Civs need to load in shell scope for the setup screen:

<ActionGroup id="shell-content" scope="shell" criteria="always">
    <Actions>
        <UpdateDatabase>
            <Item>data/civilizations.xml</Item>
        </UpdateDatabase>
    </Actions>
</ActionGroup>

---

Database Errors

"Type X not found" error

The referenced type doesn't exist or hasn't been loaded yet.

Solutions:

• Check spelling (case-sensitive)
• Ensure the type is defined in Types table
• Increase LoadOrder if depending on other mods

"Foreign key constraint failed"

A required reference is missing.

Common causes:

• Unit references non-existent UnitMovementClass
• Building references non-existent prerequisite
• Modifier references undefined RequirementSet

"Duplicate primary key"

Trying to create something that already exists.

Solutions:

• Use UPDATE SQL instead of INSERT
• Choose a unique Type name
• Use DELETE first if replacing

---

GameEffects vs Database XML

When to use GameEffects XML

Use <GameEffects xmlns="GameEffects"> for:

• Creating new modifiers
• Defining requirement sets
• Simplified modifier syntax

<GameEffects xmlns="GameEffects">
    <Modifier id="MY_MOD" collection="COLLECTION_OWNER" effect="EFFECT_CITY_ADJUST_YIELD">
        <Argument name="YieldType">YIELD_FOOD</Argument>
        <Argument name="Amount">2</Argument>
    </Modifier>
</GameEffects>

When to use Database XML

Use <Database> for:

• All table operations (Types, Units, Buildings, etc.)
• Linking modifiers to entities
• Any non-modifier data

<Database>
    <Types>
        <Row Type="UNIT_MY_UNIT" Kind="KIND_UNIT"/>
    </Types>
</Database>

Never mix them in the same file!

---

Performance Issues

Mod causes long load times

Cause	Solution
Large images	Compress textures, use DDS format
Too many modifiers	Combine similar modifiers where possible
Inefficient requirements	Use simpler requirement types

Game crashes on load

Cause	Solution
Invalid XML	Validate all XML files
Circular dependencies	Check mod dependencies for loops
Memory issues	Reduce texture sizes

---

Debugging Tips

Enable Developer Options

Add to AppOptions.txt:

CopyDatabasesToDisk 1
EnableTuner 1
EnableDebugPanels 1
UIDebugger 1
UIFileWatcher 1

Check the Logs

Key log files in %LOCALAPPDATA%\Firaxis Games\Sid Meier's Civilization VII\Logs\:

File	Contents
Database.log	Database errors and warnings
Modding.log	Mod loading information
Lua.log	Script errors (now JavaScript in Civ VII)

Export the Database

With CopyDatabasesToDisk 1, SQLite files are exported to the debug folder. Use a SQLite browser to inspect:

• DebugGameplay.sqlite - Active game data
• DebugConfiguration.sqlite - Game setup data

Use FireTuner

The FireTuner tool (in Development Tools) allows:

• Live database queries
• Console commands
• Game state inspection

---

Frequently Asked Questions

Can I use Lua like in Civ VI?

No. Civilization VII uses JavaScript for scripting. See JavaScript Overview.

How do I make content work in all ages?

Use AlwaysMet criteria or create separate ActionGroups for each age:

<Criteria id="always">
    <AlwaysMet></AlwaysMet>
</Criteria>

Why do I need two database scopes?

• Shell scope: Loads for game setup menus (civ/leader selection)
• Game scope: Loads during active gameplay

Civilizations and Leaders need both scopes to appear in setup AND work in-game.

How do I update existing game content?

Use SQL UPDATE statements:

UPDATE Units SET BaseMoves = 3 WHERE UnitType = 'UNIT_WARRIOR';

Or use XML DELETE and INSERT:

<Units>
    <Delete UnitType="UNIT_WARRIOR"/>
    <Row UnitType="UNIT_WARRIOR" BaseMoves="3" .../>
</Units>

Where are the official example mods?

In the Development Tools folder:

Steam\steamapps\common\Sid Meier's Civilization VII Development Tools\

Look for mods prefixed with fxs- (e.g., fxs-new-policies, fxs-new-narrative-events).

How do I test changes quickly?

1. Enable UIFileWatcher 1 for live UI reloading
2. Use FireTuner for database queries
3. Export database with CopyDatabasesToDisk 1
4. Start new games - saved games cache some data

---

Getting Help

Resources

• Official Documentation: In Development Tools folder
• Game Files: Study existing content in Base/modules/
• Example Mods: Look at fxs-* mods in Dev Tools

Log File Locations

Platform	Path
Windows	%LOCALAPPDATA%\Firaxis Games\Sid Meier's Civilization VII\Logs\
macOS	~/Library/Application Support/Civilization VII/Logs/
Linux	~/My Games/Sid Meier's Civilization VII/Logs/

---

See Also

• Getting Started
• modinfo Files
• XML Reference
• Modifier System