Troubleshooting

Troubleshooting

---

Known issues being investigated

Not yet confirmed bugs -- tracked on GitHub so you can follow progress or add your own findings.

Control propagation may not be setting Input API for some games. Issue #1 -- fighting/shooter-family propagation may not be setting MergedInput the way trackball-family propagation does. Possibly expected behavior (not every game's Input API dropdown lists that option) -- still being confirmed.

FFB Blaster field not found despite a paid membership. Issue #2 -- the field-discovery scan found nothing on at least one real install. Root cause not yet confirmed (could be expected if the field isn't shipped locally, or a real detection gap).

---

Registration

A game appears in TeknoParrotUI but won't launch. Its GamePath is pointing to the wrong executable or the game was not fully extracted. Open TeknoParrotUI, find the game, and point it to the correct .exe. Re-run the script and choose Repair to fix broken paths automatically where possible.

A game does not appear in TeknoParrotUI after running the script. Check the ACTION REQUIRED section printed at the end of the run. The game may need manual registration (shared executable, or its profile was already claimed by another copy of the game) or may not yet be extracted. If neither applies, check TeknoParrot-Manager.log for a registration error for that game.

A fuzzy-matched game was registered against the wrong profile. Delete that game's .xml from UserProfiles and add a forceArchetype entry in overrides.json:

{ "forceArchetype": { "WrongProfileCode": "CorrectProfileCode" } }

Re-run and the correct profile is used.

A game appears twice in TeknoParrotUI. Two UserProfile files exist for the same game (registered manually and then again by the script). Delete one of the duplicate .xml files from UserProfiles. Keep the one with the correct GamePath and any manual bindings.

---

Extraction

A game does not extract. Check that the ZIP source path is correct and the file is not corrupted. A failed extraction leaves no partial folder behind -- the next run retries automatically. Check the log for the specific error and verify the staging drive has sufficient free space.

An extraction was interrupted and the game re-extracts every run. The .extracting sentinel was not cleaned up (this should be rare -- the script uses try/finally to remove it unconditionally). Delete the file named <GameName>.extracting from your staging folder and re-run.

---

Controls

Controls are not being copied to a game. Either no reference game for that control type has been bound yet (see "Set up controls" in ACTION REQUIRED), the game is in the noPropagate list in overrides.json, or the game already has five or more bound controls and is treated as a reference game itself.

A game's controls are wrong after propagation. Use mode 9 (Restore backup) to roll back to the backup made at the start of that run, or delete the affected game's .xml from UserProfiles and re-run propagation after correcting the reference game's bindings in TeknoParrotUI.

A game's control family is wrong (e.g. a trackball game treated as a lightgun). Add a familyOverride entry in overrides.json:

{ "familyOverride": { "GameProfileCode": "trackball" } }

Valid values: button, driving, lightgun, trackball, analog, spinner.

---

Logging

The console shows [UNLOGGED] entries. The log file (TeknoParrot-Manager.log) cannot be written to. Check that the TeknoParrot folder is not read-only and you have write permission. The [UNLOGGED] entries are echoed on-screen so nothing is lost during the run.

---

HyperSpin 2

HyperSpin 2 export fails with "TeknoParrot not found in emulators.json". TeknoParrot must be set up as an emulator in HyperSpin 2 before the export can add games. Open HyperSpin 2, add TeknoParrot as an emulator (the title must contain "TeknoParrot" -- variations like "Tekno Parrot" are fine), then re-run the export.

HyperSpin 2 export fails with "Could not find a TeknoParrot game list". Verify that TeknoParrot is fully configured as an emulator in HyperSpin 2 (not just listed but with its executable path set), then try again. Check TeknoParrot-Manager.log for the exact failure detail.

---

ReShade

The Home key doesn't open the ReShade overlay. Either ReShade was not installed on that game (check whether the DLL exists in the game folder), or the game uses the Home key for another function. Change ReShade's key by editing KeyOverlay= in the game's ReShade.ini.

---

General

The script asks for settings even though I have already saved them. Either TeknoParrot-Manager.config.json was deleted, or you pressed N at the "Use these settings?" prompt. Re-enter your settings and save.

I want to reset everything and start fresh. Delete TeknoParrot-Manager.config.json (settings) and TeknoParrot-Manager.syncstate.json from your staging folder (extraction state). Your UserProfiles, game files, and backups are not affected.