Skip to content

Troubleshooting

Jump to bottom
Melancholy Sky edited this page Jun 8, 2026 · 2 revisions

Troubleshooting

First steps for any issue

  1. Check the log file — tf2autoswap.log in the tool folder records all errors with timestamps
  2. Try --dry-run to test without writing any files
  3. Use --list to verify the tool can find and search models

Common issues

TF2 not found

Message: TF2 not found. Set the path manually with the tf/ directory.

Cause: The tool checked common Steam paths and did not find TF2.

Fix: Set the path manually:

python3 tf2autoswap.py --tf2 "/path/to/steamapps/common/Team Fortress 2/tf"

Nothing found for keyword

Message: No matches for 'keyword'.

Cause: The keyword did not match any item in TF2's VPK.

Fix:

  • Check the spelling — the tool will suggest alternatives if it finds close matches
  • Try searching by the item's full friendly name (e.g. "A Head Full of Hot Air")
  • Use --list keyword to browse matches without building
  • Look up the internal keyword on backpack.tf: https://backpack.tf/overview/Item Name

Friendly names not showing

Message: (tf2_schema.py not found — friendly names and clip warnings off)

Cause: tf2_schema.py is missing from the tool folder, or the vdf library failed to install.

Fix: Make sure tf2_schema.py is in the same folder as tf2autoswap.py. The tool works without it but loses friendly names and warnings.

Windows PATH warning on first run

Message: WARNING: The script vpk.exe is installed in '...' which is not on PATH.

Cause: Standard Windows behaviour when pip installs scripts to a location not on PATH.

Fix: Nothing — this warning is harmless and does not affect how the tool works. The libraries install correctly regardless.

Output VPK not showing in preloader

Cause: The VPK may not have been imported into the preloader yet, or the preloader needs to be re-run after a TF2 update.

Fix:

  1. Open the Casual Preloader
  2. Drag the VPK onto the preloader window
  3. Tick it in the Addons tab
  4. Click Install
  5. Launch TF2

Mod installed but no visual change in-game

Possible causes:

  • Another mod in the same slot is active — untick it in the preloader
  • The preloader was not re-run after a TF2 update
  • The source and target were the same item (no visual change expected)

Custom output path not working

Cause: The path may contain characters the OS rejects, or the folder may not be writable.

Fix: The tool will fall back to the default output/ folder and tell you if a path fails. Check the log for details.

Log file

The log file is at tf2autoswap.log in the tool folder. It records:

  • Every successful build with source, target, and output path
  • Every error with a timestamp
  • Schema loading warnings

If you need to report a bug, attaching the log file helps significantly.

Reporting a bug

Open an issue on the [GitHub repository](https://github.com/TF2Autoswap/releases/issues) and include:

  • What you were trying to do
  • What happened instead
  • Your operating system and Python version
  • The relevant section of tf2autoswap.log

Clone this wiki locally