Add-ons/Toolbox/Troubleshooting

Lua add-on documentation: Toolbox overview · Add-on hub · Contribute or update documentation

This page collects recovery and diagnostic steps for Toolbox. Begin with the least disruptive check: confirm that the package is enabled, inspect the installed guide, and verify the specific feature before resetting settings or replacing saved files.

Package does not load

1. Open the add-on manager and confirm that Run is enabled for Toolbox. Newly installed packages begin disabled.
2. Enter /lua check toolbox. Correct any missing, misplaced, or incompatible package files it reports.
3. Enter /lua reload after changing files or package state.
4. Check the chat window for errors labeled Toolbox. Repeated errors can cause the sandbox to disable an add-on automatically.
5. Confirm that the client meets the package's minimum Lua API version. Toolbox 1.9.0 requires API 25, although some features require later APIs.

Community Addons should manage the package as one Lua/toolbox directory. Avoid combining a catalog installation with stray older Toolbox files at the top level of the Lua folder.

Settings do not open

Enter /toolbox or /tbx directly. If that works but Ctrl+; does not, inspect Toolbox's row under Keys in the add-on manager and resolve any shortcut conflict. /toolbox key reports the current binding.

The Docs and version windows share one of Toolbox's available add-on windows. Opening one closes the other by design; use /toolbox help or /toolbox version to reopen the desired view.

A HUD is missing

• Confirm the feature is enabled and not configured as Off on the Toolbelt page.
• Disable Only during combat temporarily, or leave settings open while positioning the strip.
• For the equipment bar, remember that it normally hides when no worn item is below the repair threshold.
• For the target strip, select a target; an independent target strip hides when no target exists.
• For notifications, verify the source's delivery route and whether the HUD has already reached its hide timer.
• Use the relevant move <x> <y> command or HUD layout buttons to recover an off-screen strip.

If the drag grip is unavailable, clear Lock Status Movement under Options → Interface → Nameplates & Chat Bubbles.

On clients with Lua API 31, version 1.7.0 automatically returns a HUD strip to the visible area after a smaller game window or larger interface scale leaves it off screen. If that recovery is unavailable, use the strip's move <x> <y> command.

Unexpected layout movement

Target space at the top or left of the Toolbelt is reserved even when no target is selected. This is intentional and keeps the player's bars from shifting during target changes. The area becomes labeled while settings are open and otherwise remains transparent to clicks.

When the buff bar—the Toolbelt's base—is disabled, attached components return to their own strips. Re-enable it or review /toolbox toolbelt to confirm the current arrangement.

Alerts or sounds are missing

1. Use the feature's Test control or /toolbox sounds test.
2. Check the overall alert volume and the individual sound's volume share.
3. For buff alerts, verify the expiration threshold, muted-effect list, and repeat-suppression interval.
4. For notifications, use /toolbox notify to inspect the source, delivery route, and sound switch.
5. If using a custom file, select it again in settings and confirm that it is a supported .ogg or .wav file in the expected Lua location.

Notifications already marked as seen are intentionally not replayed. /toolbox notify show displays current information, while the HUD clear command removes history rather than making old events new again.

Market values do not appear

Estimated values require both Estimated values (SotANET) in Toolbox and Internet permission for Toolbox in the add-on manager. Use /toolbox dd values test [item] to test the connection.

An ellipsis means a lookup is pending. Two dashes mean that no recent sale price was returned. SotANET indexes English item names; a client using another language may therefore show two dashes for most translated items, and version 1.7.0 reports that limitation. Values are cached for twenty-four hours; /toolbox dd values refresh requests fresh results. Other Toolbox features do not require the network permission.

Wrong character settings

Toolbox saves settings per character. If a layout was meant to be shared, export it from the source character or enable that character under List this character's setup, then import it on the destination character. An import is a copy, so later edits do not synchronize.

Before replacing files, press Save now, quit the game, and back up toolbox.<character>.character.json and toolbox.account.json. See configuration and backups.

On clients before Lua API 39, Toolbox keeps an additional recovery copy of settings, positions, and run history in the account file. On API 39 or later, Toolbox 1.9.0 instead uses the game's dated saved-file backups. Use Back up now and the two-step Restore control under Menu, setups, backup & reset; chat commands are also available through /toolbox settings backups and restore <number>.

A save is refused

Toolbox 1.8.0 checks the game's 256 KB limit before writing a saved-variable file. If a proposed change would exceed it, Toolbox refuses and identifies that change so other data can continue to save. Remove unused map places or overlays, or reduce other stored data, then try again. The overlay window reports its storage use.

This check was introduced in 1.8.0 and is included in the current catalog package.

Diagnosing frame hitches

Introduced in Toolbox 1.8.0. /toolbox perf [seconds] measures frame hitches during a short interval. Adding quiet pauses Toolbox timers during that test. A difference can help isolate whether Toolbox's periodic work correlates with a hitch, but a single run is diagnostic evidence rather than proof of its cause.

A new feature is unavailable

Toolbox retains API 25 as its package minimum, but several 1.7.0 features require a newer client:

• skill pause and training controls require API 27;
• farming-run map flags require API 30;
• automatic off-screen HUD recovery requires API 31;
• scene fishable-water types require API 32;
• the sound-file list requires API 33, with duplicate filename support in API 34;
• world-calendar notices and /toolbox events require API 35.
• expanded /toolbox recipe station, inventory, material-slot, and item-key details require API 37 and Toolbox 1.8.0;
• immediate world-calendar change events require API 38 and Toolbox 1.8.0; older supported clients poll periodically;
• map overlays, automatic resource maps, and last-death markers require API 30 and Toolbox 1.8.0.

The base add-on can still load when one of these optional APIs is missing; the affected feature or enhancement is omitted or reports its requirement. Versions 1.8.0 and 1.9.0 are available from the Community Addons catalog.

Resetting safely

Use the narrowest reset that addresses the problem:

Reset	Effect
XP Detailed Reset or /toolbox reset	Starts a new XP session
Loot Tracker Reset	Starts a farming run while retaining the full-day totals
/toolbox combat reset	Clears current-fight and session combat statistics
Reset all settings	Restores Toolbox configuration on the next /lua reload; statistics are kept

Export or back up the current configuration before resetting all settings.

Reporting a problem

Use the Toolbox issue tracker. Include:

• the Toolbox version and build from /toolbox version;
• the game build and Lua API version if known;
• the output or symptom, including which window or command was involved;
• whether /lua check toolbox reports a problem;
• concise steps that reproduce the issue;
• any Toolbox-labeled error text, with private information removed.

Do not publish saved-variable files without reviewing them first. A minimal reproduction and the relevant error are usually more useful than an entire personal configuration.

See also

• Toolbox
• Toolbox commands
• Toolbox configuration and backups
• Toolbox menu and location