Troubleshooting

Troubleshooting

Start with the least destructive check. Copy visible diagnostics before refreshing, and do not edit persistent JSON by hand unless a maintainer specifically directs it.

Settings page is blank

1. Hard-refresh with Ctrl+F5.
2. Confirm the installed version and branch.
3. Open browser developer tools and record the first FolderView Plus error.
4. Disable custom CSS/JS overrides.
5. Reinstall the same verified package if Diagnostics reports missing/modified runtime files.
6. Preserve /boot/config/plugins/folderview.plus before deeper recovery.

Settings has a fatal diagnostic surface and an empty-surface recovery path. Copy its report before navigating away.

Runtime banner on Docker or VMs

Copy the banner diagnostics before refreshing. Compare Docker Host list or the native VM page to confirm Unraid inventory exists. A runtime error does not necessarily mean saved folders are gone.

Docker API is unavailable or in fallback

FolderView Plus automatically prefers supported local GraphQL reads and falls back to its PHP snapshot path. You do not need to create an API key, configure a URL, or enable a repository secret.

• Unavailable/legacy: the endpoint or required query is absent; PHP fallback is expected.
• Permission/capability: the host declined the read or does not provide its shape; the API path stays disabled for that page lifecycle.
• Cooldown: a partial response, rate limit, or service error triggered a bounded retry delay; fallback remains active.
• Identity mismatch: API identities no longer match the native inventory; native/PHP structure remains authoritative. The mismatch alone does not create rows or request a host reload. A genuine native structural change is handled through the normal host reconciliation path.

If native rows and folders remain current, no repair is required. If state is stale, capture page diagnostics before refreshing, confirm Host list still shows the containers, hard-refresh once, and include the sanitized aggregate provider state in a report. Never paste tokens, cookies, raw GraphQL responses, or private container identifiers into a public issue.

Folder editor opens blank

Copy the editor bootstrap diagnostics, then check the browser console and network request for the folder. Confirm the folder still appears in Basic Settings. Do not repeatedly submit when a stale-revision conflict is reported; reload current state first.

One folder fails to display

A failed folder render should leave other folders and native container/VM controls usable. Read the localized warning and follow its link to the affected folder's settings. Saved configuration and expansion preferences are retained. On Dashboard, healthy children can appear at the top level while their parent cannot render. Reload after correcting the problem; do not recreate every folder or clear the configuration.

Safe-mode banner

Safe mode means FolderView Plus did not recognize a host surface strongly enough to modify it safely. Preserve the native page, collect diagnostics, record the Unraid version, and check compatibility. Do not force legacy selectors with custom JavaScript.

Folder View 2 or Folder View 3 conflict banner

This is different from native safe mode. FolderView Plus detected a known legacy plugin that could also inject Docker, VM, or Dashboard folders, so it paused those runtime surfaces.

1. Keep FolderView Plus installed.
2. Back up and migrate the legacy plugin data.
3. Remove only the named Folder View 2/3 plugin.
4. Refresh the webGUI.
5. Confirm the resolved banner and verify all three runtime surfaces.

Settings stays available during the pause. See FolderView3 Migration for a coordinated conversion.

Updates do not appear

• Run Plugins -> Check for Updates.
• Confirm the installed manifest tracks main or dev as intended.
• Unraid will not reinstall an identical version.
• Hard-refresh after a successful update.
• Do not manually edit the installed version file.
• Use the in-plugin update check to confirm remote version, manifest URL, and request result.
• Use the force-refresh install helper only when a maintainer directs cache troubleshooting; it deletes cached plugin package files before reinstalling.

Reverse proxy actions say Blocked by request guard

If FolderView Plus pages load through SWAG or another TLS-terminating proxy but create, save, backup, restore, or other protected actions return HTTP 403, first repeat one action through the normal Unraid address. If direct access works, keep the request guard enabled and verify the proxy authority headers.

For SWAG, include its standard proxy configuration in the Unraid location:

include /config/nginx/proxy.conf;
proxy_pass http://<unraid-address>:<unraid-port>;

A custom proxy location must provide one value for each header:

proxy_set_header Host              $host;
proxy_set_header X-Forwarded-Host  $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port  $server_port;

Do not add X-FV-Request at the proxy, remove Origin or Referer, or disable the FolderView Plus guard. After changing SWAG, reload Nginx, hard-refresh Unraid, and retry one protected action.

If it still fails, export a sanitized support bundle while using the failing proxy URL. system.requestSecurity reports bounded authority, Origin, and Referer reason codes without recording hostnames, IP addresses, ports, or raw header values. Include that sanitized bundle with the Unraid version, FolderView Plus version, and whether direct access worked.

A protected save fails

Copy the support code and follow the message for missing page security information, nonce preparation, rejected Unraid session checks, or proxy origin mismatches. Refresh and sign back into Unraid if needed. For proxy-only failures, use the header checks above; never disable request protections. Reproduce once, then open Diagnostics in the same browser tab to retain the bounded sanitized request-failure history.

Import fails validation

Confirm the file is a FolderView Plus/eligible legacy export and matches Docker versus VM. Re-open the preview, use Merge safely for normal migration, and resolve reported hierarchy or identity conflicts. Never remove schema/type fields simply to bypass validation.

Icons are missing

1. Run Diagnostics and inspect icon-pack state.
2. Confirm the persistent icon archive exists.
3. Confirm the runtime link resolves to the active cache.
4. Reinstall the verified package to reactivate the pack.
5. For uploaded icons, confirm they remain under persistent plugin configuration.
6. Open Custom Icon Manager and check quota, usage, rename/replacement, and the selected filename.
7. If Diagnostics recommends Repair missing custom-icon references, review the backup notice and run it once.

See Installation and Upgrades for paths.

Custom icon upload returns empty JSON

The uploader attempts the existing inline path once when the multipart response is empty or cannot be parsed. A successful retry completes the upload normally; an unsuccessful retry still shows an error. Ordinary validation and permission errors are not automatically retried. Test a small PNG and the originally failing image, then confirm the selected icon survives saving and refresh. If it still fails, capture the exact message and upload request's HTTP status/response, excluding cookies and authentication headers. A green storage-health card alone does not prove the upload request worked.

Collapsed folders are blank

• Expand the folder to confirm actual members.
• Check Preview-tab inclusion separately from membership.
• Check child-folder preview depth.
• Clear temporary runtime filters.
• Disable lazy preview temporarily for diagnosis.
• Compare Host list/native rows.

An explanatory empty preview can be correct when every member is intentionally excluded.

A preview container menu does not open

1. Confirm the folder's Preview Context is Default or Advanced, then record which mode fails.
2. Hard-refresh after updating FolderView Plus.
3. Test the icon, name, status, and remaining card surface in both the first visible preview row and any affected later row.
4. Test keyboard activation with Enter and Space.
5. Confirm WebUI, logs, and console quick actions still perform only their own action.
6. Repeat with Unraid Basic View and Advanced View, and note whether the affected folder has child folders.
7. Leave Preview Rows set to the failing value (1, 2, 3, 4, or Unlimited) while reproducing.
8. Navigate to Settings and export a sanitized support bundle.

Inspect uiTelemetry.dockerDiagnostics.previewContextBridge. A successful record shows the row mode/position, binding and handler-integrity counts, activation category, input method, and dispatch outcome. If it reports available: false, return to Docker, reproduce once after the hard refresh, and export again without changing the Unraid hostname or access method.

Defaults, hover, grayscale, and mixed ordering

• Defaults: open Edit folder defaults under Docker or VMs in Settings, save the profile, and create a new folder to verify inheritance. Existing folders change only through the separate Apply to all action.
• Advanced hover: select Preview Context -> Advanced and Activation mode -> Hover. Mouse hover works on computers with a touchscreen and a fine pointer; touch-only devices use tap/click. Show preview only on hover is a separate visibility option.
• Stopped icons: set Preview status -> Grayscale stopped icons and turn Preview icon grayscale off to keep running members colored. Verify both Icon and label and Only icon (clean).
• Mixed Docker order: saved folder and standalone-container slots survive refresh. Folder sorting operates within those slots; newly created folders begin at the top until positioned. Native unassigned-item positions are not imported from FolderView3.

Native rows briefly appear

FolderView Plus preserves native content during bootstrap rather than hiding the page indefinitely. A short transition can be normal. Repeated flashing or a page that never settles is not; collect console/runtime diagnostics and test without overrides.

Folder status text is invisible or has the wrong theme color

1. Update FolderView Plus and hard-refresh the affected Dashboard, Docker, or VM page.
2. Edit the folder, open Status, and enable Theme default beside Text. Resetting the status palette also restores this mode.
3. Verify that a light Unraid theme produces dark status text and a dark theme produces light status text.
4. If a fixed color is intentional, choose it with the Text picker and verify contrast in every theme you use. Lock status colors preserves that explicit override.
5. If the problem remains, reproduce it on the affected page and export a sanitized support bundle. In folder-integrity diagnostics, textMode: theme means no custom text color is active; textMode: custom confirms an explicit override.

Folder rows refresh repeatedly

Increase the live-refresh interval or disable it temporarily. Switch to Adaptive/Maximum performance, reduce preview depth, disable custom scripts, and look for host/plugin observers repeatedly rebuilding the same area.

Host list or view switching looks wrong

Use Reset view, clear filters, return zoom to 100%, and hard-refresh. Host list should display native Docker rows without FolderView grouping; changing view must not delete configuration.

A Docker folder disappeared after using Hide

Hide is reversible and does not delete folder configuration or change container assignments. Open View -> Hidden folders on the Docker page. Revealed rows are dimmed and labeled Hidden; restore the affected folder from its menu or choose Restore all hidden folders. Immediately after hiding, the 10-second Undo notice provides the fastest recovery. Host list continues to show native container rows even while a FolderView row is hidden.

If recovery controls do not appear, confirm the installed version/branch, hard-refresh, switch back to FolderView, and clear temporary filters. Do not recreate the folder or edit JSON by hand.

A custom WebUI profile opens no tabs or fewer tabs than expected

Open the folder menu and review the profile's ready count. A selected container opens only when it is a current direct member, running, not paused, and exposes a safe WebUI. Stopped, paused, removed, or unavailable members are skipped without being removed from the saved profile.

Edit the folder and open WebUI Profiles to inspect unavailable selections. If the ready count is nonzero but no tabs open, allow popups for the Unraid host and retry from the same user gesture. Do not copy private WebUI URLs into a public report; a sanitized support bundle exports profile health counts without profile names, container names, or addresses.

Dashboard cards or names are clipped

Try Classic layout, reset density/view controls, test 100% zoom and a supported browser, then disable custom CSS. Compare desktop and mobile widths. While the defect is visible, use Dashboard View options -> Capture layout diagnostics before navigating to Settings Diagnostics. Add a Privacy-reviewed screenshot if it materially shows the issue.

Fullwidth, Accordion, Inset, and Embossed cards should fill the widget's available width; Compact Matrix cards should fill their grid slot. Classic and Legacy retain native tile styling. Space outside the Docker/VM widget belongs to Unraid's Dashboard layout and is not evidence of a narrow folder card.

Hierarchy scan reports problems

• Self-parent, orphan-parent, and cycle findings are link errors that Tree repair can reset to root.
• Depth beyond six and empty branches are advisory; reorganize them manually.
• Repair requires current revision state, confirmation, and a verified backup.
• Use the offered undo if the repaired root placement is not what you intended.
• Do not hand-edit parent IDs in JSON to silence a finding.

Privacy choice is not applied

Confirm Privacy is enabled for the correct Docker/VM type and the individual mask is selected. Close/reopen previews and menus, then trigger a runtime refresh. Remember that FolderView Plus cannot mask browser developer tools or unrelated Unraid/plugin surfaces.

Settings or runtime is slow

• Switch from Standard to Adaptive or Maximum performance.
• Enable lazy preview with a sensible threshold.
• Increase live-refresh interval.
• Reduce collapsed preview depth/contents.
• Disable custom scripts.
• Run Diagnostics performance retest.
• Capture folder/member counts without exposing names.

Backup or restore fails

Stop further destructive operations. Record the error and Activity entry. Confirm flash-device free space and permissions, inspect Diagnostics storage health, and compare available non-empty snapshots. Preserve the current persistent directory before manual intervention.

Remember that Restore Latest skips zero-folder snapshots. Direct restore can still apply an explicitly selected empty snapshot, so confirm the selected snapshot count before proceeding.

Start order does not match

Refresh the preview and confirm unmanaged, Follow Docker page, or Custom batch mode. Review the remaining-container policy, per-container waits, batch delays, native autostart switches, disabled disclosure, stale entries, and missing/duplicate identities. Sync only in a managed mode after the displayed plan is complete. Changes apply at the next Docker service start; verify during a controlled maintenance window.

Capture a visual problem correctly

Runtime support bundles cannot reconstruct the layout you saw earlier. Reproduce the issue, capture page/layout diagnostics on the affected Docker, VM, or Dashboard surface before leaving it, then confirm freshness in Settings Diagnostics. Captures are bounded and sanitized, but still preview the final bundle before sharing.

Paths for diagnosis

Purpose	Path
Persistent configuration	/boot/config/plugins/folderview.plus
Installed runtime	/usr/local/emhttp/plugins/folderview.plus
Icon RAM cache	/tmp/folderview.plus-assets
Disposable plugin cache	/tmp/folderview.plus-cache
Ephemeral security state	/var/run/folderview.plus
Installed version	/boot/config/plugins/folderview.plus/version

Do not publish directory contents without reviewing them.

Legacy CSS/JS overrides

Compatibility roots for folder.view, folder.view2, and folder.view3 can still load. Temporarily rename/disable overrides when diagnosing. If the issue disappears, migrate to documented tokens and stable selectors rather than re-enabling broad legacy rules unchanged.

Escalate with evidence

If the issue remains, use Activity, Diagnostics, and Support to build a sanitized report.