Troubleshooting

Troubleshooting

Start with the read-only diagnostic:

one-bit-bureau doctor

It checks the installation record, plugin and theme ownership, Desktop state, shell IPC, helpers, icons, and optional GTK3 app chrome without changing anything. Use one-bit-bureau status for the shorter installation summary. If either reports that One-Bit Bureau is not fully installed, use the installation-specific sections below.

Setup reports conflicting standalone plugins

Disable the listed plugin before retrying. One-Bit Bureau refuses enabled copies of:

• henri.desktop-icons
• crmne.active-window
• expose.window-overview
• rosakodu.dock

These duplicate surfaces One-Bit Bureau already supplies. Setup does not silently disable someone else’s plugin.

The verified installer says One-Bit Bureau is already installed

Use:

one-bit-bureau update

If a previous failed attempt left only a disabled canonical plugin checkout and no ownership record, rerun the verified install block from the same immutable release. It adopts the checkout only when the origin is canonical, the tree is clean, and its full commit exactly matches the verified release metadata.

A plugin, theme, font, branding, or command target already exists

Setup refuses unowned collisions. Do not delete the reported path blindly.

1. Inspect the path and decide whether it belongs to an earlier One-Bit Bureau installation.
2. If one-bit-bureau remove works, use it so ownership and restoration rules apply.
3. If the ownership record is missing, preserve the existing path and diagnose why it exists before moving or removing it.

This conservative behavior prevents setup from overwriting unrelated user files.

Update refuses a dirty checkout

One-Bit Bureau updates only a clean Git-managed canonical checkout. Inspect:

git -C "$HOME/.config/omarchy/plugins/io.github.regionallyfamous.one-bit-bureau" status

Commit or preserve intentional changes elsewhere before restoring the installed checkout to a clean state. Update also refuses a changed remote origin or a plugin/theme commit mismatch.

An app has the wrong icon

Open Manage Icons from the dock and select the app.

• Choose Automatic for One-Bit matching plus grayscale fallback.
• Choose Native for the app’s original full-color icon.
• Pick one of the 32 roles for a manual One-Bit assignment.
• Choose a local custom file when the app needs its own art.

CLI examples:

one-bit-bureau icon native firefox
one-bit-bureau icon auto firefox
one-bit-bureau icon pack set firefox browser
one-bit-bureau icon list

See Icons and App Associations for the complete resolution order.

An unmatched app is grayscale

That is the Automatic fallback. One-Bit Bureau preserves the native silhouette and detail but removes color so unknown apps fit the one-bit dock.

Restore full color:

one-bit-bureau icon native <app-id>

A custom icon is rejected

Use a regular local image file. One-Bit Bureau rejects remote URLs, inline data, unsafe links, special files, malformed names, and unbounded input. Open the configuration folder with:

one-bit-bureau icon folder

The dock appears on the wrong display

Inspect the resolved output:

one-bit-bureau dock getScreen

Set the preferred output using the exact Hyprland monitor name:

one-bit-bureau dock setScreen DP-1

The dock owns one persisted output. If it disconnects, the dock falls back and returns when the preferred output reconnects.

The dock does not reveal

Move the pointer to the bottom edge on the dock’s resolved display. If a menu, icon picker, window preview, drag operation, or app-switcher HUD is active, the dock deliberately suppresses normal auto-hide transitions.

Toggle auto-hide through the dock menu or:

one-bit-bureau dock toggleAutoHide

The overview does not open

Try the coordinator:

one-bit-bureau overview

If that fails, confirm the plugin is enabled and inspect one-bit-bureau status. The hot corner can be disabled or moved in overview settings even while the command continues to work.

The Inspector says an object or window is stale

The Inspector keeps its layout stable when the underlying file, app window, or workspace disappears. Close it and select the live object again. A stale action remains visible but unavailable because One-Bit Bureau re-resolves the target immediately before acting.

A desktop route is rejected

The routing slip names the selected items, operation, and destination. A refusal usually means the target vanished, is outside the configured Desktop boundary, cannot accept one of the selected object kinds, already contains a colliding name, or the 64-item selection bound was exceeded. No partial action begins when preflight rejects the route.

A receipt has no Undo button

This is deliberate for Copy, Trash, folders, launchers, partial batches, changed destination files, and occupied original paths. Undo appears only for an unchanged regular-file move with a durable journal and a currently provable reverse operation. The receipt never promises a broader history than the helper can safely reverse.

Desktop files are off

Your XDG user-directory configuration explicitly maps Desktop to your home directory, which means Desktop files are disabled. One-Bit Bureau keeps that choice and does not recreate ~/Desktop. Change the Desktop location through your XDG user-directory configuration if you want real files on the desktop, then refresh One-Bit Bureau.

GTK3 app chrome will not turn off

One-Bit Bureau refuses to restore a backup when its ownership record, hashes, or paths no longer match. Start with one-bit-bureau doctor. If you intentionally want to remove the preview and doctor confirms the owned repair is available, run:

one-bit-bureau doctor --repair app-chrome-off

GTK4/libadwaita, Qt, Chromium profiles, LibreOffice profiles, packages, and system files are never part of this preview.

The Window Ledger looks stale

Close and reopen it after an application creates or closes a window. One dock icon represents the application; the Ledger represents its current titled windows. Activate and Close revalidate the compositor address, and a vanished known-running window does not fall through to launching a duplicate app.

The Workspace Board has no destination or refuses a move

The board lists existing ordinary numeric Hyprland workspaces only. It does not invent a workspace, include special scratchpad workspaces, or accept a stale window address. Open the destination workspace once so it exists, reopen Overview, choose it with Control+Left or Control+Right, and use Control+Shift+Enter. The board stays open after a successful move.

Font symbols are missing

Departure Mono does not include Omarchy’s Nerd Font symbol set. Use:

one-bit-bureau font use krypton

Monaspace Krypton NF is the recommended whole-desktop font.

Removal refuses to continue

Removal stops when the ownership record is missing, unsafe, inconsistent, or no longer points to the canonical owned paths. This is intentional: the uninstaller will not guess which files are safe to delete.

Preserve the reported paths and collect:

one-bit-bureau status
git -C "$HOME/.config/omarchy/plugins/io.github.regionallyfamous.one-bit-bureau" status
git -C "$HOME/.config/omarchy/plugins/io.github.regionallyfamous.one-bit-bureau" remote -v

Open a GitHub issue with the error, Omarchy version, and this output. Do not include secrets or private Desktop filenames.

Report a bug

Open an issue with:

• Omarchy version or commit
• One-Bit Bureau version from manifest.json
• Display names, resolutions, and scale when the issue is visual
• Exact command and error text
• Whether the install is public Git-managed or local development mode
• A screenshot when it does not expose private information