Skip to content

Troubleshooting

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

Troubleshooting

First steps for any issue

  1. Check the log file — output/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. As of v4.7 this warning is suppressed automatically. If you are on an older version, upgrading to v4.7 resolves it.

Risk warning prompt not appearing / tool skips straight to menu

Cause: The acknowledgement flag file already exists from a previous run.

Fix: This is expected behaviour — the full warning only shows on first run. If you need to reset it, delete output/.acknowledged from the tool folder.

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 output/tf2autoswap.log inside the tool folder. It records:

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

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/main/issues) and include:

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

Clone this wiki locally