BlackAddonsDocs
DocsStart hereTroubleshooting

Troubleshooting

Work from the symptom below. Change one setting at a time and repeat the same event. The feature guides describe what should happen. A missing trigger, a hidden HUD, and a startup failure need different checks.

BlackAddons does not load

  1. Confirm that the launched instance is Fabric 26.1.2 or 26.2 and that the BlackAddons jar targets that exact Minecraft version.
  2. Check that instance’s mods folder for Fabric API and Fabric Language Kotlin. Read the first dependency error in the launcher or logs/latest.log; it usually names the missing or incompatible mod.
  3. Keep exactly one main BlackAddons jar, Legit or Cheat. Remove an older duplicate from this instance. Extras is optional but needs a matching main jar.
  4. If it crashes before the menu, save the full crash report and logs/latest.log. Compare a separate minimal Fabric instance with only BlackAddons and its required dependencies, then add other mods back in groups to isolate a conflict.

Copy the config folder before testing whether a saved setting is involved. A startup crash alone is not a reason to discard it.

  1. Enter /blackaddons in world. If that works, inspect Options > Controls > Key Binds for the BlackAddons menu key (default Right Shift). The hotkey opens it only when another screen is not open.
  2. Clear the ClickGUI search box and check the right category. Empty categories can be hidden. Extras adds an Extras section; Cheat features need the Cheat edition.
  3. Confirm the expected jar is in the active instance’s mods folder and restart Minecraft. Features and addons are discovered once at startup.
  4. If the menu opens but has no features at all, attach logs/latest.log and the installed jar names. That is a different symptom from one feature being absent.

Settings or HUD positions do not persist

  1. Confirm you launch the same Minecraft instance each time. Separate launcher profiles can use separate config folders.
  2. Use Configs > Save Now before closing. The main feature and HUD file is the instance’s config/blackaddons.json.
  3. Reload discards unsaved changes; reset controls ask for confirmation. Copy the file before manual edits or a reset, and keep its JSON valid.
  4. If saving fails, inspect latest.log and file permissions. Preserve the original file; replacing a damaged one without a copy can lose settings.

Switching editions or temporarily removing an addon should retain its unavailable feature and HUD entries in the config. Reinstall the matching addon or edition if you want those controls to reappear.

Chat, cosmetics, or live updates do not connect

  1. Use /b net to see the connection state and note its text. A network or service outage can affect backend features while local UI features still work.
  2. /b reauth retries sign-in. /b net socket restarts live updates; /b net restart restarts the wider networking and sign-in path.
  3. In Settings > Connection, disabling Live Updates switches immediate push updates to periodic refresh and stops reporting your online presence. It is not a master switch for all backend features.
  4. If only one cosmetic is absent, check ownership and Visual > Cosmetics > Show Other Players. If only chat fails, test /b chat and a prefixed message. A failed BlackAddons send should stay out of server chat.
  5. Record the connection state and error text. Do not post sign-in codes or private conversations.

A feature is enabled but nothing changes

  1. Reproduce its real trigger: a dungeon run, a key entity, a screenshot, a status effect, XP gain, a backend-owned cosmetic, or a bound key. Many features are intentionally idle elsewhere.
  2. Check sub-switches. Screen QoL has separate overlay and toast controls; Particle Hider needs a distance or type filter; Auto Clicker can be stopped by any enabled filter.
  3. Repeat the same event once with the feature off and once on. Note whether the event never occurred, occurred with no visual difference, or produced the wrong result.
  4. If another mod changes the same rendering or input path, repeat in a separate minimal instance with BlackAddons and required dependencies. Keep the game version and settings the same.

HUD element is invisible, clipped, or misplaced

  1. Enable the owning feature and open /b hud. The editor gives a preview even if live data is absent. Drag it into view and check its own scale.
  2. Check Settings > Scaling. HUD Scale multiplies all elements; Auto Scale affects how resizing changes them. Recheck after changing Minecraft GUI Scale or window size.
  3. Return to the right game context. Key Timer only appears during a key pickup window; Skill Display fades after XP; Stat Bars need SkyBlock action-bar stats; Dungeon Map needs a recognized dungeon.
  4. If the preview is missing, check the correct edition/addon and sub-switches. If the preview is visible but the live element is absent during a valid event, capture both screens and the event timing.

Dungeon Map or score looks wrong

  1. Confirm the run is recognized as Catacombs and Dungeon Map is enabled. Hide In Boss can intentionally remove it during the boss phase.
  2. In legit mode, wait for discovery. Room Prediction applies to unopened 1x1 rooms; Cheat edition room reveal is in the map’s Cheats group.
  3. Compare Calculation Method and secret-goal assumptions before comparing the estimate with the final score. Speed, unfinished puzzles, crypts, Mimic, Prince, Bat, and Paul can affect it.
  4. If Solo Clears is on, its board score deliberately treats skips and the mayor bonus differently from the game scoreboard. Check Board before comparing totals.
  5. For a repeatable mismatch, record the floor, elapsed time, deaths, puzzles, secrets, crypts, bonus indicators, mayor state, and both the map and scoreboard.

Simon Says does not highlight or follows the wrong sequence

  1. Confirm F7/M7 Simon Says is in its active phase and Simon Says is enabled.
  2. If colors blend into your resource pack, adjust First Color, Second Color, and Other Color.
  3. Use Reset Solver after a missed pattern or device reset. Block Wrong Clicks can cancel an incorrect click; sneak to override it while diagnosing.
  4. In Cheat edition, choose Auto Solve or AutoSS Triggerbot, stand inside Activation Radius, and check that Override Key has not switched automation off. Reset State affects automation; Reset Solver affects the pattern reader.
  5. Record a clip starting before the pattern plays. A still image cannot show a sequence error.

Solo Clear did not appear on a board

  1. Enable Solo Clears before a solo F7/M7 run. Check its indicator and chat announcements to see whether the run opened, completed, was refused, or failed to upload.
  2. Check Board and the 300-point target. Skips allowed and No skips calculate the on-screen target differently.
  3. Open /b sc after the run. Your runs view can show a result and why it did not make a board.
  4. If upload failed, check /b net and preserve the displayed error before repeating a run.

FME edit does not show

  1. Enable Legit FME. Its editor can open while FME is disabled, but disabled rendering will not show replacements.
  2. In /b fme, check the active profile, scope, and context. A Location edit applies only in its location; a Dungeon Room edit needs the matching scanned room.
  3. Confirm the rule or group is enabled and the replacement exists. In Edit Mode, right-click replaces, left-click restores, and middle-click places a visual block where allowed.
  4. Open a screen to exit Edit Mode before testing normal block interaction. Use /b fme undo if the wrong block changed.
  5. If the block still does not redraw, record the original and replacement blocks, location/room, installed render mods, and whether the editor list contains the edit. Compare a minimal instance to narrow a renderer conflict.

/b fme clear clears edits in the active FME profile. Use editor controls for a single context or rule.

  1. Check Interface > Screenshots. With it on, a normal screenshot produces a preview notice instead of Minecraft’s chat line.
  2. Wait briefly for the thumbnail; the image can be saved before the preview appears.
  3. Open /b screenshots and confirm the image exists in the active instance’s screenshots folder.
  4. If saving fails with Screenshots off too, investigate Minecraft’s screenshot path or file permissions. If saving succeeds but the preview fails, provide latest.log and the image size.

Storage Overlay is empty or stale

  1. Verify Extras is installed and Storage Overlay is on. Open each ender-chest page or backpack on SkyBlock at least once; an uncaptured page has no snapshot to search.
  2. Confirm the account and SkyBlock profile. The cache is scoped to both.
  3. Storage Browser controls the overlay; /ec, /enderchest -> Storage changes where bare commands open. A numbered /enderchest <page> still opens that page.
  4. Reopen a page after items change. Clear Cache discards the current profile’s snapshots; use it only if you intend to recapture them.
  5. A currently open page uses real server slots for item moves. Distinguish that live page from an offline cached one when reporting a click issue.

An action or shortcut does not run

  1. Open /b action and verify the active profile. Actions, waypoints, and shortcuts belong to a profile.
  2. Check that the action and its required steps are enabled. Check the exact chat condition, area transition, keybind, or alias. Use a unique alias name.
  3. Run /b action status. If it is busy, /b action stop cancels the sequence and clears its queue.
  4. Reduce the action to one harmless step, test, then add steps back until the failure is clear. Capture the editor, trigger, and any chat/error output.

Low FPS or a short freeze

  1. Note whether the problem starts at launch, in one screen, on dungeon entry, or after enabling a feature. Compare the same scene with that feature off and on.
  2. Enable Dev > Freeze Capture before a repeated stall. It writes thread stacks after a roughly 200 ms client stall to config/blackaddons/dev/freezes/.
  3. Keep several captures from the same symptom with latest.log. One stack sample alone does not establish the cause.
  4. If the issue only occurs with another rendering or optimization mod, note its version and compare a minimal instance.

What to include in a report

  • Minecraft and Fabric Loader versions, BlackAddons version and edition, Extras version if installed, and the active launcher instance.
  • The feature and setting values, location or dungeon phase, and numbered steps that reproduce the symptom.
  • Expected and actual results, and whether the same event works with the feature off or in a minimal instance.
  • Relevant logs/latest.log, crash report, freeze captures, or a short clip for input and timing problems.

Remove sign-in codes, private chat, account data, and server addresses you do not want public before sharing.