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.
• Structural fallback: API identities no longer match the native inventory; FolderView Plus requests one native refresh instead of creating unknown rows.

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.

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.

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.

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.
2. Hard-refresh after updating FolderView Plus.
3. Test the icon, name, and status in both the first visible preview row and the 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. Leave Preview Rows set to the failing value (2, 3, 4, or Unlimited) while reproducing.
7. 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.

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 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.

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.

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.