Troubleshooting

Start with Settings > Operations and the process's startup output. Confirm the version/build, active region, data directory, and most recent successful check before changing configuration. Use the table to find the relevant guide.

Startup and access

Symptom	What to check
Source launch fails with SQLite/runtime errors	Run node --version; source requires Node 22.13+. Use the compiled backend or a standalone package.
Launcher not found	Current checkout scripts are in launchers/; the published v1.2.0 source ZIP has them at its root.
Address already in use	Check for another GearBeacon process, installed task/service, or container on the configured port. Stop the duplicate rather than running against the same data twice.
Browser cannot reach the server from another device	localhost refers to that device. Check access mode, bind, firewall, and Docker host port mapping. Use authenticated private mode for intended LAN/VPN access.
Owner setup asks for a token	Read it locally from the running process, service log, or docker compose logs gearbeacon; never post it publicly.
Owner password is lost	Follow the stopped-process password-file recovery in Security and access.
HTTP 421 / rejected Host	Match the configured hostname and proxy authority. Local mode permits only loopback hosts. Preserve Host correctly at the proxy.
HTTP 403 / Origin or CSRF error	Use the canonical dashboard origin, refresh the session/page, and check exact proxy/public-URL configuration. Do not disable validation.
Login succeeds but does not persist	Check whether secure cookies are configured while browsing HTTP. Use the intended HTTPS URL and correct public URL/proxy settings.
.env change has no effect	Source launchers do not implicitly load it; Compose only forwards mapped variables; existing browser-saved settings override many environment defaults.

Platform process/log commands: Windows, macOS, Linux, Docker. Proxy-specific configuration is in Reverse proxy.

Watches, collections, and prices

Symptom	Explanation / next step
Checked collection items are not saved	Select Create collection, Save changes, or Add watches. Selection checkboxes are pending edits; collection alert toggles save separately and automatically.
Save reports success but members disappear after an update	Restart the actual GearBeacon backend and refresh the browser. Check Operations shows the expected version/build; the current editor verifies server membership support and the returned items.
An individual card disappears after assigning it	Group items in collections hides assigned individual cards in All collections. Use View items or the collection filter. The watch remains monitored.
An archived member is not visible	Grouping keeps archived memberships grouped away. Open Manage collections > Archived > View watches.
An item appears in more than one project	Projects share one watch; this does not duplicate its individual jobs. Independently watching Any variant and an exact variant does create two watches.
Collection total is incomplete	Enter missing actual purchase totals or wait for missing catalog prices. Unknown amounts are not treated as zero.
Budget changed after a new catalog price	Recorded spending remains fixed; remaining-unit estimates follow confirmed prices. Shipping/extra checkout costs are not automatically included.
Editing a target affects another collection	Targets belong to the shared watch. Desired/purchased quantities and actual spending belong to each project.
Ready-to-buy counts differ from the filtered grid	Overview counts cover the current region independently of filters and use confirmed evidence plus remaining demand.
Store and dashboard disagree briefly	Restocks can be confirmed in one complete check; sellouts/price/status changes need two. Check pending evidence and region/variant selection.
Stock history is partial or unknown	History starts with retained observations, and failures/restarts/pending checks create explicit gaps. Older change records cannot reconstruct exact coverage.

Read Watchlist and Browse, Collections, and Stock insights for the full behavior.

Notifications

1. Confirm the channel is configured and enabled, then run that channel's test.
2. Inspect the relevant Activity entry. A confirmed event does not necessarily qualify for a notification.
3. Check global event choices, All activity, the watch's override/target/pause/purchased state, and any named collection-only suppression.
4. Check quiet hours, timezone, digest time, grouping, and cooldown. Review pending/failed delivery details in Operations.
5. Correct transport/credential issues before retrying failed jobs. Keep SMTP TLS and certificate validation enabled.

An already qualifying watch/collection does not send a catch-up alert merely because a condition was enabled. It establishes a baseline and waits for a qualifying transition. Collection alerts must be explicitly enabled; pausing an item does not pause its project's readiness alert. An active Collection alerts only mode does suppress member notifications, including All activity and immediate restocks.

Browser popups require permission and a running page. Use a server channel to receive notifications with the browser closed. Notifications describe the queued observation; the Store may change while delivery is delayed. See Alerts and Email/webhooks.

Storage, recovery, and updates

Symptom	What to check
Existing watches appear missing after installation/move	Verify the actual data directory. Portable and service defaults differ; Compose project/volume changes may attach an empty volume. Preserve both locations before recovering.
Secondary backup fails	Check mount availability, absolute container/service path, permissions for the actual process identity, and Linux systemd writable-path restrictions.
Primary succeeded but secondary failed	The primary backup is retained; resolve the secondary warning and test again.
Saved notification credentials cannot decrypt	Restore the matching secrets.key or re-enter secrets. Watch/history data is independent of those encrypted credentials.
Recovery import rejected as too large	The application limit is a 256 MiB request body; a reverse proxy may have a smaller limit.
Older executable rejects the database/export	Restore a backup compatible with the older version as part of rollback. Schema v11 / export v7 needs a supporting build.
Container uses an unexpected version after an update	Persist GEARBEACON_IMAGE_TAG in project configuration. The Docker helper sets it only for its invocation.
Update changed files but behavior is old	Restart the task/service/container and refresh the browser; verify exact runtime build in Operations.

Use Backups and recovery before replacing data and Updates and rollback before changing versions.

Request useful help

Include the GearBeacon version/build, installation type, operating system/architecture, affected region, exact steps, expected versus actual behavior, and a redacted error message. Run diagnostics and attach the Support bundle after reviewing it. State whether restarting the process and refreshing the browser changed the result.

Do not attach the live database, encryption key, owner/setup/session tokens, channel URLs, credentials, unredacted logs, or Activity exports to public issues. Use the private reporting process for security findings.