Skip to content

Offline Behavior

Glassy Companion is designed to never silently lose a capture. If your Glassy server is unreachable — network outage, server restart, VPN change, or just a flaky café Wi-Fi — your captures are queued locally and synced automatically when connectivity returns.

What Happens When You Capture Offline

  1. You trigger any capture (Quick Save, Smart capture, element pick, highlight).
  2. The extension attempts to reach your configured Glassy server.
  3. If the request fails (network error, 5xx response, timeout), the capture is added to the offline queue in your browser's local storage.
  4. A badge indicator on the toolbar icon shows the number of queued items.
  5. Every 60 seconds, the extension checks connectivity and attempts to flush the queue.

Your captures never disappear. They wait in the queue until a flush succeeds.

The Offline Queue

The queue lives in chrome.storage.local under the glassy_offline_queue key. It stores the full capture payload — title, URL, Markdown, tags, collection — everything needed to replay the save exactly as you intended it.

Queue flush algorithm (v2.5.0)

The flush is now O(n) — the extension processes all queued items in parallel, then applies the outcomes in a single storage read-modify-write. Items that were enqueued during a flush are preserved (the apply step re-reads at commit time). This means a full queue flushes in one round-trip instead of one round-trip per item.

What counts as "success"

A queued item is removed when the server responds with a 2xx status. On a non-retryable error (e.g., 400 Bad Request) it is also removed — there's no point retrying a malformed payload. On network errors or 5xx responses, the attempt counter increments; after three failures the item stays in the queue but is flagged for manual review.

Inspecting the Queue

To see what's queued:

  1. Open the Glassy Companion popup.
  2. Go to Settings → Debug → Offline Queue (requires developer mode).
  3. Each item shows its attempt count and last error.

Alternatively, run in the browser console:

chrome.storage.local.get('glassy_offline_queue', console.log);

What Is and Isn't Queued

Action Queued offline?
Quick Save / Smart capture ✓ Yes
Text highlight (context menu) ✓ Yes
Element pick ✓ Yes
Quick Note ✓ Yes
Screenshot upload ✓ Capture is queued; image upload retried separately
Login / auth ✗ No — requires connectivity
Tag/collection list refresh ✗ No — uses cached data

Self-Hosted Instances

If you run a self-hosted Glassy server, the offline queue works identically — as long as your extension is configured to point at your server's URL (Settings → Server URL). Captures queue against whichever server is configured.

Note

Screenshot images are uploaded to POST /api/ext/capture-image on your server. If the server is offline, the image upload fails separately from the capture text. The capture text (title, URL, Markdown body, tags) is still queued and will sync; the screenshot embed will be absent until you re-capture with the server online.

Troubleshooting

Queue stuck / not flushing

  • Check that your server URL in Settings is correct and reachable.
  • Open the extension popup; if you see a red badge, the last flush hit an error. Tap the badge to see the error detail.
  • If you recently changed your server URL, the queue may have old requests that point at the old host. Clear them via Settings → Debug → Clear Queue.

Capture succeeded but item missing from Glassy

This is rare with v2.5.0+ but possible if the server accepted the request but the DB write failed. Check server logs (docker logs glassy-dash-prod | grep captures) for 500 errors at the capture endpoint.

"Content script error" badge

If extractor.js fails to read the page (e.g., a PDF, restricted page, or browser-internal URL), a CONTENT_SCRIPT_ERROR is reported. The capture still proceeds with whatever metadata was available (URL and browser-reported title). The error is visible in the extension's background service worker log.