Skip to main content

Troubleshooting XML

Common XML issues and how to fix them.

Validation Tools​

Online Validators​

  1. FreeFormatter XML Validator
  2. XMLvalidation.com
  3. W3Schools XML Validator

VS Code Validation​

  1. Install "XML" extension
  2. Files validate automatically
  3. Errors show in problems panel

Command Line​

# Using Windows PowerShell
[xml](Get-Content "file.xml")

# Using WSL/Linux
xmllint --noout file.xml

Common Errors​

1. Unclosed Tags​

Error: Expected closing tag

<!-- WRONG -->
<vehicle>
  <name>Car</vehicle>
</name>

<!-- CORRECT -->
<vehicle>
  <name>Car</name>
</vehicle>

2. Missing XML Declaration​

Error: Not a valid XML document

<!-- WRONG - Missing declaration -->
<root>
  <item>content</item>
</root>

<!-- CORRECT -->
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>content</item>
</root>

3. Special Character Issues​

Error: Unexpected character

<!-- WRONG -->
<description>Speed & handling</description>
<note>Value must be < 100</note>

<!-- CORRECT -->
<description>Speed &amp; handling</description>
<note>Value must be &lt; 100</note>

Escape sequences:

  • & = &amp;
  • < = &lt;
  • > = &gt;
  • " = &quot;
  • ' = &apos;

4. Improper Nesting​

Error: Tag mismatch

<!-- WRONG -->
<parent>
  <child>
    <grandchild>content
  </child>
</grandchild>
</parent>

<!-- CORRECT -->
<parent>
  <child>
    <grandchild>content</grandchild>
  </child>
</parent>

5. Duplicate IDs​

Error: Vehicle spawn fails or wrong data loads

<!-- WRONG -->
<colour id="0">
  <name>Black</name>
</colour>
<colour id="0">
  <name>White</name>
</colour>

<!-- CORRECT -->
<colour id="0">
  <name>Black</name>
</colour>
<colour id="1">
  <name>White</name>
</colour>

6. Case Sensitivity​

Error: Vehicle doesn't spawn, properties don't apply

<!-- WRONG - Mismatched case -->
vehicles.meta: <modelName>MyVehicle</modelName>
carvariations.xml: <Item>
                     <modelName>myvehicle</modelName>

<!-- CORRECT - Exact match -->
vehicles.meta: <modelName>myvehicle</modelName>
carvariations.xml: <Item>
                     <modelName>myvehicle</modelName>

7. Attribute Quotes​

Error: Attribute without quotes

<!-- WRONG -->
<wheel id=0 modelName=sport_wheel />

<!-- CORRECT -->
<wheel id="0" modelName="sport_wheel" />

FiveM-Specific Issues​

Vehicle Won't Spawn​

Possible causes:

  1. Invalid modelName in vehicles.meta

    <!-- Check: modelName matches 3D model file exactly -->
    <modelName>myvehicle</modelName>

  2. Missing handlingId reference

    <!-- Verify handlingId exists in handling.meta -->
    <handlingId>MYVEHICLE</handlingId>

    <!-- In handling.meta, must have matching entry -->
    <Item type="CHandlingData">
      <handlingName>MYVEHICLE</handlingName>

  3. Syntax error in file

    • Validate XML with online tool
    • Check for unclosed tags
    • Verify special characters escaped

Colors Not Applying​

  1. IDs don't match between files

    <!-- carcols.xml -->
    <colour id="100">
      <name>Custom Red</name>
    </colour>

    <!-- carvariations.xml must reference same ID -->
    <primaryColour>100</primaryColour>

  2. RGB values out of range

    <!-- WRONG - Values must be 0-255 -->
    <r>300</r>

    <!-- CORRECT -->
    <r>255</r>

  3. Invalid colour IDs

    <!-- Ensure all referenced IDs exist in carcols.xml -->
    <primaryColour>9999</primaryColour>  <!-- May not exist! -->

Wheels Not Showing​

  1. Invalid model names

    <!-- Verify wheel model names are correct -->
    <wheel id="0" modelName="wheel_sport_01" />  <!-- Must exist -->

  2. Wrong wheel slot

    <!-- Use slot 19 for wheels, not other slots -->
    <ModType id="19">
      <ModName>Wheels</ModName>
    </ModType>

Handling Feels Wrong​

  1. Reference mismatch

    <!-- vehicles.meta -->
    <handlingId>MYVEHICLE</handlingId>

    <!-- handling.meta must match exactly -->
    <handlingName>MYVEHICLE</handlingName>

  2. Invalid physics values

    <!-- Values should be realistic -->
    <fMass>1500.0</fMass>           <!-- 800-5000 typical -->
    <fAcceleration>0.8</fAcceleration>  <!-- 0.5-1.5 typical -->

Debugging Steps​

Step 1: Validate XML​

# Online or local validation
xmllint --noout file.xml

Step 2: Check References​

  • All modelNames match
  • All IDs are unique
  • All cross-file references exist

Step 3: Test Individual Files​

  • Replace with known-good vehicle
  • If it works, issue is in your file
  • If not, check resource setup

Step 4: Check Console​

  • Look for error messages
  • Search for file not found errors
  • Check model loading status

Step 5: Simplify​

  • Start with basic vehicle
  • Add modifications one at a time
  • Test after each change

Recovery from Corrupted Files​

Backup & Restore​

# Copy your files before modifying
copy vehicles.meta vehicles.meta.backup
copy carcols.xml carcols.xml.backup
copy carvariations.xml carvariations.xml.backup

# If something breaks, restore from backup
copy vehicles.meta.backup vehicles.meta

Git for Version Control​

git init
git add *.xml *.meta
git commit -m "Initial vehicle setup"

# If you make mistakes:
git diff                    # See changes
git checkout -- file.xml    # Restore file

Prevention Tips​

  1. Always backup before editing
  2. Validate after changes - Use tools immediately
  3. Test incrementally - Add one change at a time
  4. Use version control - Track all changes
  5. Keep examples - Reference working files
  6. Document changes - Note what you modified
  7. Test thoroughly - Verify in-game

Advanced Debugging​

XML Pretty Print​

# Reformat XML for better readability
python -m xml.dom.minidom file.xml > file_pretty.xml

Find Duplicates​

# Search for duplicate IDs
grep -o 'id="[0-9]*"' carcols.xml | sort | uniq -d

Validate Against Schema​

Create an XSD schema and validate against it:

xmllint --schema schema.xsd file.xml

Getting Help​

If issues persist:

  1. Check the FiveM documentation - docs.fivem.net
  2. Community forums - forum.fivem.net
  3. Discord communities - Various FiveM modding servers
  4. GitHub issues - Report bugs to tool creators

Quick Checklist​

  • XML validates without errors
  • All tags are properly closed
  • Special characters are escaped
  • IDs are unique
  • Cross-file references match
  • Case sensitivity is correct
  • Attributes have quotes
  • Numbers are in valid ranges
  • Files are backed up
  • Changes tested in-game