Troubleshooting

Start with the smallest read-only check that separates controller, network, credential, capability, and router-state failures. Do not retry a router write until you know the previous operation's terminal state.

Interface quick checks

These symptoms concern the v0.1.8 interface. Check the executable version and use its matching embedded UI; earlier releases do not include every workspace.

Symptom	Explanation or safe next check
Reports, Alerts, Firmware, Integrations, or Cards/List are missing	These workspaces were introduced in v0.1.6 and remain in v0.1.8. Do not copy only new UI assets onto an older daemon; use a matching build and read the schema migration boundary
Firmware or Integrations disappeared from the sidebar	In v0.1.8, open Settings → Firmware or Settings → Integrations. Existing /firmware and /integrations bookmarks open those sections; this is a navigation change, not a removed capability
Settings opens Network instead of a bookmarked maintenance tab	Diagnostics requires Administrator/Owner and Backup & Restore requires Owner. A disallowed section safely falls back to Network and replaces the invalid history entry; verify the signed-in role rather than changing the URL to bypass access
Reports export becomes unavailable after changing the period	Expected while the newly selected period loads. v0.1.8 hides the previous result and blocks export until the completed data matches the selected period and refresh. Retry a failed load; do not treat the old period as current
Device count differs from the filtered cards	Fleet summaries and filtered results have different scopes. Read Showing … of …; clear search/status filters before diagnosing missing inventory
Client signal count is smaller than the matching total	Signal readings describes only this page and only measured RSSI; Matching clients spans all pages under the filters. Unknown connection is not proof of wired attachment
A topology move is not saved	Finish the drag, check the storage notice, and use the same signed-in account, controller origin, browser, and Current/History mode. Clearing site data or blocked storage removes persistence
A new/offline node is arranged differently	New nodes use automatic placement; changed placed/unplaced classification discards incompatible saved coordinates. This preserves evidence, not a cabling change
Reports has a gap or unavailable comparison	Check the exact gateway/series and both periods' completed buckets. No missing traffic or uptime is estimated; shorter ranges may provide more useful coverage
Alert stays unknown or does not reach its hold time	Restore fresh, consecutive evidence for its selected device and condition. A gap resets continuity; unknown is not a clear or successful interval
Alert fires but delivery fails	Check the configured generic webhook and bounded delivery status as Owner. Do not retry by recreating rules or assume Telegram/Slack-specific payload compatibility
Firmware check cannot identify a candidate	Re-probe changed board/target/release facts, inspect the catalogue reason, and use the Firmware guide. Never force a mismatched image or interpret a match as validated flash readiness
Official firmware catalogue cannot be checked	Verify DNS resolution and HTTPS access to downloads.openwrt.org from the controller host, then retry. A transient DNS failure is not evidence that router firmware is outdated; a failed check confirms no version status
AdGuard or WireGuard check is unavailable	Confirm Administrator/Owner role, explicit connection/read grant, reachability, and the integration-specific instructions. No automatic service or helper install is attempted
Demo action says read-only	Intentional: it has no controller/router connection. Use synthetic data only, and do not enter real credentials or upload a backup
v0.1.5 binary refuses schema 24 or 25	Use v0.1.8 for schema 25, or restore the matching pre-upgrade schema-23 database/keyring/passphrase and v0.1.5 binary/image. Do not edit schema metadata or replace only the executable

For responsive navigation, install requirements, and theme preference, see Mobile and installed app. An installed browser shortcut is not offline access, a native app, or Web Push support.

First five checks

1. Confirm the executable version:

   oonfeewrtd -version

   Expected for this guide: v0.1.8.

2. Check controller liveness using the same listener configuration as the running process:

   oonfeewrtd -listen 127.0.0.1:8080 -healthcheck

3. Read controller logs. For a container:

   docker logs --tail 200 oonfeewrt

4. Confirm the data directory, keyring, and passphrase file still refer to the same controller.

5. If the controller runs but fleet data is wrong, open the relevant device and read its freshness, source coverage, and capability gaps before changing it.

Controller does not start

data directory ... must be an absolute path

Use an absolute path:

oonfeewrtd -data-dir /absolute/path/to/oonfeewrt-data

This guard prevents an unexpected working directory from creating a second empty controller.

listen ... address already in use

Another process owns the configured address. Stop the duplicate controller or choose a different listener. Make the same change in the healthcheck, reverse proxy, and container mapping. Do not start two controllers against the same data directory.

OONFEE_PASSPHRASE is set

Remove that environment value and put the passphrase in a protected file:

unset OONFEE_PASSPHRASE
chmod 600 /absolute/path/to/passphrase
export OONFEE_PASSPHRASE_FILE=/absolute/path/to/passphrase

Passphrase file is not accepted

Check that it is a non-empty regular file, readable by the daemon user, and not group/world-readable:

ls -l /absolute/path/to/passphrase
chmod 600 /absolute/path/to/passphrase

For the supplied container, the file must be readable by UID 65532 unless the container is explicitly run as another UID/GID.

Wrong passphrase or keyring error

Stop. Do not delete keyring.json or let the controller initialize a new data directory beside the existing database. A new keyring cannot decrypt existing credentials.

Restore the exact matching set:

• oonfeewrt.db;
• sibling keyring.json; and
• the passphrase/passphrase file that opens that keyring.

Validate an isolated copy with the recovery helper.

Healthcheck fails but the process appears to run

-healthcheck probes the listener passed through -listen or OONFEE_LISTEN; it does not discover another process's flags. Use the same address/port as the running controller. If a reverse proxy is healthy but the direct check fails, diagnose the controller listener before the proxy.

The check expects HTTP 200 and body exactly ok within four seconds. It does not require the passphrase or open the database, so a successful healthcheck is only HTTP liveness—not proof that sign-in, storage, or routers work.

Browser cannot connect or repeatedly returns to sign-in

1. Verify /healthz directly from the browser host.
2. Check that the proxy forwards ordinary HTTP and WebSocket upgrades.
3. For TLS termination, preserve X-Forwarded-Proto: https so Secure cookies are issued correctly.
4. Do not mix access through an IP address and DNS hostname; cookies are scoped to a host/domain and path. Keep scheme, host, and port consistent as well, because the controller separately enforces same-origin checks on mutations.
5. Remember that sessions are intentionally lost on controller restart and expire after 12 idle hours or seven absolute days.

If a password was changed, account disabled/deleted, role changed, or session revoked, signing out is expected. Ask an Owner to inspect the account/session state rather than repeatedly attempting credentials.

Discovery finds no routers

oonfeeWRT discovery does not use ARP tables or mDNS. It plans eligible, directly attached IPv4 networks, makes bounded TCP/HTTP probes, and identifies stock rpcd from an unauthenticated /ubus object list. A default bridged container usually exposes only its container interfaces to that planner, so an empty or skipped LAN scan is expected rather than proof that no router exists.

• Use Adopt a device → add by address.
• Ensure the controller process or container network namespace can route to the management IP.
• Read the scan plan, skipped networks, and route-failure details; a /31, /32, IPv6, point-to-point/tunnel, link-local, or broader-than-/22 interface is deliberately not swept automatically.
• On Linux only, host networking can expose eligible host LAN interfaces to the same TCP scanner if you accept the listener/firewall implications.
• A firewall, nonstandard uhttpd port, HTTPS-only endpoint without the HTTPS scan option, or inaccessible /ubus endpoint can prevent a fingerprint even when the host answers.
• On Docker Desktop, use add-by-address.

Discovery is not required for adoption, polling, or Apply.

Inspect or adoption cannot reach a router

From the controller host, verify:

• the management address is correct;
• SSH is reachable on the configured/default port;
• uhttpd exposes the ubus handler;
• the supplied device administrator username/password works;
• a firewall or management VLAN is not blocking the controller; and
• the address does not point to a different device.

Inspect is read-only. Use it to confirm model, firmware, interface, and capability facts before authorizing adoption. Do not weaken router authentication or expose SSH publicly to make the check pass.

SSH host key or device fingerprint changed

Treat an unexpected identity change as a security event or device replacement. Verify the current key/fingerprint through an independent trusted path such as local LuCI, physical access, or a known console. Re-adopt only after establishing why it changed (for example, a deliberate reflash). Never accept the change blindly.

Inspect succeeds but compatibility export is unavailable

This can be intentional fail-closed behavior. The compatibility document is a separate, server-built allowlist. Text is normalized, redacted, and bounded; the controller omits the report if interface names, function/switch values, radio/port counts, or encoded output still fall outside strict safety bounds. Inspect can still display the ordinary result and adds a note explaining that the sanitized report was unavailable.

1. Confirm both daemon and UI are the same v0.1.2-or-newer release; for this guide, both should be v0.1.8.
2. Repeat read-only Inspect once after confirming the target address and credentials. It makes a fresh probe, but do not loop it aggressively.
3. Record the controller version, router model/OpenWrt version, the displayed inspection limits, and the exact availability note.
4. Report the omission as a sanitizer/compatibility issue. Do not work around it by publishing the full Inspect API response, router logs, ubus dumps, or SSH command output; those are not the share-safe format.

No stored report can be recovered later because compatibility export is not a controller job and is not persisted.

A monitor-only router is missing configuration actions

This is the intended authority boundary, not a capability failure. A monitor-only device uses the distinct read-only oonfeewrt-monitor ACL and can contribute polling, inventory, telemetry, events, and topology. It is excluded from Preview, Apply, desired/site configuration, optional LLDP installation/ configuration/removal, wireless-neighbor mutations, and other package/config/ remove operations. Existing LLDP observation, ACL maintenance, and un-adoption remain available.

A supported RF scan is also available after its own disruption acknowledgement. It is an active, transient observation that may take the serving radio off-channel and interrupt clients; it does not grant persistent configuration authority.

If observation fails, verify the existing route or VPN, firewall, SSH, and HTTP or HTTPS /ubus access from the controller host. oonfeeWRT does not establish cross-subnet reachability. If configuration authority is genuinely required, back up the router, resolve who owns DHCP/routing/firewall/Wi-Fi, then use the documented un-adopt/re-adopt workflow to choose Managed. Do not bypass the mode through direct API calls.

A feature says unavailable, unsupported, partial, or stale

These states mean different things:

• unsupported/unavailable: the router, driver, package, or ACL did not expose the fact;
• partial: some sources answered, but not enough for a complete claim;
• stale: prior evidence exists but a current poll did not refresh it;
• empty: a source answered successfully with no rows.

Use Re-probe capabilities after an intentional firmware/package/ACL change. Read the exact source reason. Do not install packages manually merely to remove an unavailable badge; adoption promises not to do that, and optional capability state needs a recorded plan and rollback.

LLDP package history is empty or the Devices screen failed before v0.1.8

An existing LLDP ownership ledger can contain a null or omitted package list. v0.1.8 normalizes that value to an array for both status and successful action responses. The Devices screen then reports Controller-added packages: none recorded instead of failing to render. This means the ledger records no added packages; it is not proof that lldpd was already installed.

Upgrade the controller and refresh the browser. Do not reinstall LLDP, re-adopt the router, reset the controller, or edit its database for this display case. LLDP error reporting, ownership, rollback, and un-adoption gates are unchanged. Investigate a genuine installation or rollback error separately; v0.1.8 does not claim to solve every LLDP failure.

Shared-PHY Preview reports duplicate or ambiguous radio targets

v0.1.8 uses each configured UCI wifi-device section key as authoritative, even when several configured radios share one physical PHY. If an older probe collapsed those identities, do not retry a failed Apply: it may already have changed router configuration before ownership recording failed.

1. Inspect the durable Apply outcome and current wireless configuration.
2. Re-probe capabilities for the affected device.
3. Generate a fresh Preview and confirm distinct section targets for every intended radio and matching wifi-iface references.
4. Authorize Apply separately only after that Preview is unambiguous.

Invalid, duplicate, or ambiguous identities are rejected before router writes. Do not edit the database, clear ownership, re-adopt, or use repeated Apply as recovery. If ambiguity remains, stop and provide only a sanitized compatibility report and redacted Preview/error evidence; omit addresses, MACs, SSIDs, and credentials. See the Wi-Fi recovery sequence.

An IPv6 router-advertisement warning remains after choosing Disabled

Saving Disabled changes controller desired state only. Generate a fresh Preview and inspect the option-level plan. On the management LAN, the sections remain foreign: v0.1.8 can patch only the allowlisted IPv6 options on the exact existing LAN/DHCP and supported conventional WAN targets. It cannot create, claim, rename, or delete them. Resolve any missing, ambiguous, wrong-type, or static-IPv6 blocker deliberately, then Apply once. Static IPv6 addresses, prefixes, or gateways are never deleted implicitly.

After a successful Apply, verify the affected network and Logs → General rather than deleting log rows. The active card is independent of table filters and pagination. It represents only recent evidence with a fresh router-log cursor; retained event history is separate. Its occurrence count and latest timestamp should stop advancing once OpenWrt stops producing the message. Fifteen minutes of continuous fresh quiet can classify the condition as historical. Stale collection, a continuity gap, or an unsettled producer epoch is unknown—not proof that the fix worked.

Exact repeat compaction shipped in v0.1.1: new matching messages increment one condition per router-log producer epoch, and startup converts matching legacy raw rows into that bounded form while preserving original receive evidence. v0.1.4 adds the filter/page-independent current classifier and guided card, including router names, occurrence totals, and Review IPv6 and Apply. Fresh quiet clears the banner, but an old compacted row can remain until normal retention. Neither compaction nor deleting controller evidence suppresses the router's own logd output. Router managed also does not clear the source; it simply stops oonfeeWRT from changing existing IPv6 option values.

Understand notices without treating every gap as a fault

The v0.1.8 UI separates routine information from conditions that need attention. Expand a notice for the exact source, what can be done, and what the controller cannot establish. Historical or unsupported evidence is not erased to make a screen appear healthy.

Message	Meaning	What to do
Earlier router-log history is unavailable	Current collection is fresh, but an earlier interval could not be bridged	Keep the controller and router reachable. The continuity marker expires 24 hours after the last gap if no new gap occurs; current reads cannot reconstruct missing history
Router-log coverage is missing or out of date	A current source is missing, stale, or unknown	Open the named device, check reachability and capability details, and restore connectivity. Refresh controller access only for a reported permission denial; then allow the normal collection cycle
Channel classification / DFS unavailable	The controller has no explicit evidence to distinguish DFS from other restrictions	Keep the reported Restricted/unknown labels. Check the router's wireless settings; no controller refresh or RF scan resolves this implementation limit
History gaps / No history	Some or all completed intervals have no stored metric	Keep collection running, allow a completed interval and storage flush, and inspect source-specific gaps. Use a shorter chart range for recent data. Missing history is not downtime or zero activity
Optional LLDP capability is not installed	Richer neighbour evidence is optional, not a requirement for ordinary monitoring	Leave it uninstalled unless you need that evidence. Review the separate installation plan and consent before making any router changes
Refresh failed, offline device, clock skew, or configuration blocker	There is a current failure, time-quality concern, or safety gate	Read the specific remedy. These remain prominent; do not dismiss them as a historical gap or retry a write blindly

One router-log discontinuity reason is log ring no longer contains the cursor. The collector did not find its saved continuation position in the latest bounded batch (up to 512 entries). That can follow a long collection pause or high message volume; it does not by itself distinguish ring overwrite from the request's batch limit. Continuous controller/network availability reduces gaps. If they recur during healthy collection, investigate excessive router logging. Increasing a buffer alone is not a guaranteed fix, and deleting controller evidence does not recover the missing events.

Router clock status is unavailable or reports a large offset

On an adoption created before v0.1.4, ordinary management keeps working but the new UTC read is outside the older scoped ACL. Review and apply the updated controller-access payload from the device screen. Re-adoption is not required, and this read does not set the router clock. Refresh only when the controller names clock access as unavailable and that status is wanted; it is not a generic fix for surprising historical timestamps.

If an offset remains, compare the controller and router over an independently trusted shell without changing either clock:

date -u +%s
ubus call luci getUnixtime
ubus call luci getLocaltime

Check the router's NTP synchronization, upstream reachability, and timezone configuration through OpenWrt. v0.1.4 prefers luci.getUnixtime and uses luci.getLocaltime only as a compatibility fallback, so local timezone display must not be treated as UTC. The General Logs warning is based only on a fresh, successful UTC comparison and appears at an absolute offset of five minutes or more. Events remain ordered by router source time, and fixing the clock does not rewrite already stored timestamps.

Preview is blocked

Read the named gate. Common causes include:

• a device is unreachable;
• capability evidence is missing or stale;
• a foreign/human-managed section conflicts with desired state, including an unsafe or ambiguous target for the narrow management-LAN IPv6 option patch;
• uncommitted router edits are present;
• the change touches the controller's management path;
• hardware/driver facts do not prove a requested option; or
• the Preview was generated for older desired/router state.

Resolve the condition and generate a fresh Preview. A prior preview/acknowledgement does not authorize a changed plan.

Monitor-only devices are deliberately absent from the Preview target fleet. If a direct per-device request names one, the server refuses it rather than silently widening authority.

A named policy set cannot save, render, or delete

• Saving requires a unique nonblank name, 1–1,024 canonical exact MAC members, and a stored local observation for every member from the currently adopted Managed Gateway.
• A firewall rule may use direct source MACs or one named set, never both.
• Missing/empty references fail validation and rendering closed.
• Deletion is refused while any enabled or disabled firewall rule references the set's stable ID.

Schema 23 stores source-relative client evidence in client_observations, keyed by device and MAC. Monitor-only observations neither satisfy nor contaminate the managed-Gateway proof, including after a monitoring device is un-adopted. Set creation/update, direct or set-backed MAC Secure drafts, and new blocked/fixed-address intent are refused when a referenced MAC lacks a stored local observation from the currently adopted Managed Gateway. An upstream or unknown observation from that Gateway is also insufficient. Active MAC intent blocks Preview until every referenced client has that local proof.

Complete a successful client poll on the Managed Gateway if the picker is missing an expected client or Preview reports missing source evidence. Upgrades initially lack schema-23 observations, and portable restore deliberately clears them rather than treating evidence gathered by another controller instance as write authority. A successful Managed Gateway poll re-establishes the proof. Authorization rejects observations older than the normal 30-day client- retention cutoff or more than five minutes in the future even before cleanup. Cleanup also prunes provenance at the 30-day cutoff when desired intent keeps the merged client row; that intent stays stored but blocks Preview until the Gateway observes the MAC locally again. For a referenced set, find every set-backed row in the Master Table and move or remove those rules before deletion. After any membership edit, generate a fresh Preview and verify the exact resolved MACs; saving the set alone does not alter the managed Gateway.

Removing a monitoring router cannot manufacture managed-Gateway proof; its observations never participate in this gate. Prefer a network/zone or explicit IPv4 policy that identifies the actual enforcement scope, or wait for a successful Managed Gateway poll. Existing blocked/fixed-address intent may be cleared one client at a time even while the gate is active.

Apply failed or its outcome is uncertain

Do not click Apply again immediately.

1. Read the durable operation and per-device receipt.
2. Wait through the displayed OpenWrt rollback window.
3. Test the management address from the controller host.
4. Use independent LuCI/SSH access to inspect pending UCI, named owned sections, and any exact management-LAN IPv6 patch targets in the receipt.
5. Determine whether OpenWrt reverted or the controller confirmed.
6. After the device is stable, generate a new Preview.
7. Download diagnostics if evidence remains unclear.

The operation continues independently of the browser request. A reload should read status, not duplicate the write. See Safety model.

Device is online but topology shows “Unplaced”

Online status proves controller reachability, not a current physical parent. Dynamic bridge FDB/neighbor evidence can age out, and BusyBox FDB output may not identify VLAN provenance. The topology deliberately avoids inventing a link.

Check source coverage and last-observed times. If durable physical adjacency is worth a router package/service, review the optional LLDP plan. Do not install lldpd outside the controller and then expect its rollback ledger to be accurate.

v0.1.4 uses fresh FDB, STP-port, LLDP, association, and managed-peer evidence to project a transitive path in the current view. A possible upstream transit candidate is hidden only while a matching direct placement and every required hop are fresh. Raw candidate intervals remain in history. If direct proof closes or a required source becomes stale, fails, or is ambiguous, the candidate can reappear rather than being hidden by old evidence.

If a client or managed device appears under several direct parents:

1. Expand every edge's Evidence cell and note which device and physical port observed the MAC.
2. Check FDB, STP port mapping, direct association/placement, and LLDP source freshness for each hop.
3. Wait for one complete fresh topology cycle after reconnecting or moving a device; do not delete inventory to force a layout.
4. Treat a clean FDB-only edge as inferred. vlan_available=false means stock BusyBox supplied no VLAN provenance; by itself that is neutral, not a source failure.
5. Add the optional LLDP workflow only when stronger managed-peer evidence is worth its package, service, and rollback footprint.

WAN route or WAN throughput is unavailable

Online state does not prove an effective Internet route, and a route does not prove that a matching durable counter series exists. The WAN selector introduced in v0.1.3 requires one composite observation: the installed main-table IPv4 route and netifd's logical interfaces must both answer in the same slow topology poll.

Start read-only:

1. Confirm the controller is v0.1.8 and the device is adopted as a managed Gateway.

2. Allow one topology cycle (normally up to 15 minutes) after startup, adoption, or a route change, then read the device's source/degradation reason.

3. From an independently trusted router shell, if appropriate, inspect the two sources without changing them:

   /sbin/ip -4 route show table all
   ubus call network.interface dump

   These outputs contain addresses and network configuration. Do not post them publicly without careful redaction.

4. Verify there is one usable lowest-metric IPv4 default in table main/254 and that its kernel dev maps to exactly one up netifd interface with a default route. PPPoE commonly maps logical wan to l3_device pppoe-wan.

5. If the route is shown but throughput is not, wait for completed five-minute rollups and check whether the exact kernel route interface appears in both the device's interface series and route evidence.

Distinct equal-metric main-table defaults, ECMP/multipath (nexthop), an unmappable kernel device, malformed command output, a refused ACL call, or either half of the batch failing leave the selection unavailable. Source-bound and non-main policy-table routes are ignored by this selector; a coexisting unique usable main-table default can still be observed, but it may differ from the route chosen for policy traffic. mwan3 and custom policy routing are not modeled. The collector preserves the last proved network scope on failure, but stale evidence does not become a current Dashboard WAN path.

Do not change route metrics, PPPoE, firewall, or failover configuration merely to populate a chart. If the route layout is intentional but outside the modeled scope, treat WAN selection as unavailable in v0.1.8. Re-probing capabilities does not force or repair this topology observation.

Charts are initially empty after startup or adoption

Many charts use completed five-minute rollups. A current poll can prove a device is online before the first complete durable bucket exists. Counter-based metrics also need a baseline and a later sample before a delta is meaningful.

Wait for a complete collection window and check source freshness. Do not interpret missing points as zero traffic, zero utilization, or zero clients.

RF scan cannot run or has no suggestion

A scan requires the selected radio/source capability, fresh identity, and an explicit disruption acknowledgement. It may take the serving radio off-channel and is never scheduled automatically.

A channel suggestion additionally requires:

• a completed scan no older than 24 hours;
• non-stale radio state; and
• a channel plan observed within 15 minutes.

An ACL refresh or capability probe does not run a scan. The published hardware evidence includes one explicitly authorized C6 5 GHz scan (14 BSS entries, suggested channel 44); it does not authorize future scans or prove identical behavior on another radio.

WRT3200ACM configuration is present but no BSS comes on air

The published Marvell 88W8964/mwlwifi evidence found that WPA3/SAE and PMF can wedge the radio until a physical cold power cycle. A valid UCI section or reported-enabled interface is not independent on-air proof.

Inspect OpenWrt logs for missing AP-ENABLED/hostapd failures, let any active rollback finish, then use a known-safe configuration. The demonstrated boundary was WPA2-only, PMF disabled, FT disabled, and 802.11k/v enabled after cold boot. Do not manufacture repeated Applies while the radio is wedged.

Controller-host speed test fails or affects users

The test runs from the controller/container through Cloudflare, not from a router. It can use about 15 MiB and temporarily saturate the WAN for up to 30 seconds. Only one test may be active.

• Wait for or cancel the active job before starting another.
• Verify the controller host/container has HTTPS and DNS access to the provider.
• Run during a quiet period if saturation affects clients.
• Do not interpret the result as router-local forwarding performance.
• Loaded latency and jitter are unavailable in v0.1.8.

Diagnostics or backup download expired

Completed diagnostics and backup-export downloads expire after 15 minutes. Restore upload/preview working state expires after 30 minutes. Start a new job; do not search temporary controller directories for an expired artifact.

Diagnostics makes no live router call. Portable backup contains sensitive controller state and should be transferred only over loopback or trusted TLS.

Recovery helper rejects a backup

oonfeewrt-recoverycheck requires a current-schema, isolated database with its exact sibling keyring. Common failures:

• OONFEE_PASSPHRASE_FILE is missing, unreadable, or wrong;
• keyring.json is absent or belongs to another snapshot;
• the database or keyring is a symlink;
• a non-empty -wal or -journal indicates an unsafe/incomplete copy; or
• the database schema is older/newer than the helper supports.

Create a consistent SQLite .backup or stop the controller cleanly before copying. Never “repair” the pair by deleting sidecars from the live controller; work on an isolated copy and preserve the originals.

Router writes remain suppressed after restore

This is expected. Read-only monitoring may resume, but restored desired state is not automatically Applied. An Owner must:

1. inspect the restored devices, credentials, WLANs, networks, policies, and operation history;
2. reauthenticate with the current controller account password;
3. understand that automatic 802.11k neighbour maintenance resumes too; and
4. enter exact RESUME ROUTER WRITES for the matching restore.

Do not remove the gate merely to clear the banner.

Un-adoption is blocked

An optional LLDP capability ledger may still own packages/configuration/service state. Review and complete its rollback first. This prevents un-adoption from orphaning package residue.

If the router is permanently lost, forced controller removal may be the only remaining inventory action. Preserve the exact manual cleanup recipe and audit record; forced removal cannot prove the inaccessible router is clean.

Upgrade or rollback trouble

v0.1.8 retains schema 25 from v0.1.6 and v0.1.7. From v0.1.5 it applies the existing schema 23 → 24 → 25 migrations: persistent alert state, then encrypted AdGuard Home settings. It does not configure a router, create a rule, connect a service, install a helper, or enable firmware execution. Older supported versions first apply their existing migrations, including v0.1.5's management-mode, policy-set, and provenance changes. The v0.1.5 daemon cannot open schema 24 or 25.

To roll back to v0.1.5, stop the controller and restore its matching untouched schema-23 database, keyring.json, runtime passphrase, and executable/image. Keep the newer recovery unit separately. Do not change the schema number by hand or feed a schema-25 backup to an older controller. A portable restore into v0.1.8 pauses external alert delivery and cancels queued notifications; review the receiver and explicitly re-enable delivery after restoration.

To roll back to v0.1.4, stop the controller and restore the matching pre-upgrade schema-20 database, keyring.json, runtime passphrase, and old binary/image together. Replacing only the executable or image tag is not a valid rollback. Upgrade does not require re-adoption or silently change ACLs; selecting Monitor only later uses the separately reviewed ACL lifecycle.

Rollback to historical v0.1.0-rc.1 is different: that daemon uses schema 17 and must not open schema-20, schema-23, or schema-25 state. Stop the controller and restore the untouched pre-upgrade schema-17 database, matching keyring, passphrase file, and old binary/image together. Migration/rollback does not revert router configuration.

Escalation bundle

Before reporting a problem, collect:

• exact oonfeewrtd -version output;
• installation method and host platform;
• controller logs around the event;
• affected router model and OpenWrt version;
• the UI's capability/source reason and timestamps;
• the durable Apply/scan/speed-test/backup/restore job ID if relevant; and
• a freshly generated redacted diagnostics ZIP.

Do not include the database, keyring, passphrase, router administrator password, Wi-Fi key, session cookies, or unredacted private logs in a public issue.