# Troubleshooting

Start by closing IMVU, re-running the relevant install or restore command, and
restarting IMVU. Many failures are caused by patched files being in use or by
IMVU loading old assets until restart.

## Installer and Windows

| Problem | Fix |
| --- | --- |
| SmartScreen says "Unknown publisher" | Click **More info** and **Run anyway**, or use `install.ps1` |
| Defender blocks or deletes the `.exe` | Use `install.ps1`; it applies the same patch without the PyInstaller binary |
| Installer cannot patch files | Close IMVU and rerun |
| Installer hash does not match release notes | Do not run it; download again from official Releases |
| GUI installer appears stuck | Close IMVU manually, then wait for the installer log to continue |

## Emoji

| Problem | Likely Cause | Fix |
| --- | --- | --- |
| Picker button missing | IMVU was not restarted or patch did not apply | Close IMVU, reinstall, reopen |
| Emoji show as hex boxes | `library.zip` or chat JS was not patched | Re-run install and check for errors |
| Emoji images are broken | CDN access blocked | Allow `cdn.jsdelivr.net`; first load needs internet |
| Picker is clipped | Embedded browser layout clipping | Capture a screenshot and open an issue |
| Shortcuts do not behave as expected | Picker setting or older injected JS | Re-run patch, then check the gear settings |
| Favorites disappeared | Embedded browser storage was cleared | Re-add favorites; they are local only |

Restore emoji:

```powershell
python -m imvu_toolkit emoji restore
```

## DPI

| Problem | First Step |
| --- | --- |
| Click targets are offset | `python -m imvu_toolkit tools scale-window --watch` |
| Client is usable but blurry | Keep scaling helper as baseline before testing internal patches |
| Dialog/card clipping | Try `python -m imvu_toolkit dpi dialog-scaling` |
| White seam near the tab/scene boundary | Try `python -m imvu_toolkit dpi white-line` |
| Room overlay hitboxes are wrong | Run probe/audit, then test clean-layout and room-hitboxes |

Restore a DPI patch by passing its script restore flag:

```powershell
python -m imvu_toolkit dpi clean-layout -- --restore
```

See [DPI Fixes](DPI-Fixes.md) for the full command list.

## Backups

Backups are written beside the patched IMVU files:

```text
%APPDATA%\IMVUClient\library.zip.bak-emoji-*
%APPDATA%\IMVUClient\ui\chrome\imvuContent.jar.bak-emoji-*
```

DPI patches use suffixes such as `bak-cleanlayout-*`, `bak-hitbox-*`, and
`bak-clickremap-*`.

## Good Bug Reports

Include:

- Windows version and display scale, such as `250% / 240 DPI`.
- IMVU Classic version or build date, if known.
- Toolkit version from `python -m imvu_toolkit --version`.
- Install command used.
- Whether the issue affects emoji, DPI, or both.
- Screenshots for visual layout problems.
- Probe or audit output for DPI issues.
- Whether `im/common.pyo` or only `im/common.py` exists in `library.zip`.

Use the repository bug report template when opening an issue.