Skip to content

Common Issues

Quick solutions to frequently encountered problems.

Sync Problems

Notes Not Appearing on Other Devices

  1. Check your internet connection
  2. Open the Account HUD and verify you're signed in
  3. Pull down to refresh the note list
  4. Check that sync isn't paused in Settings

Changes Not Saving

  1. Ensure you're online (offline mode has limitations)
  2. Check if you've hit your storage limit in the Account HUD
  3. Try closing and reopening the note
  4. Refresh the browser or restart the app

Info

Notes show a small sync indicator when saving. If you see a spinning icon for more than 30 seconds, there may be a connection issue.

Storage and Limits

Storage Limit Reached

When you see an amber indicator in the Account HUD:

  1. Open the Account HUD (your avatar or storage display)
  2. Review which notes use the most space
  3. Archive notes you don't need active
  4. Consider upgrading to Pro for more storage

Warning

Your data is never deleted automatically. You control what gets archived.

Understanding Storage Display

  • Green: Under 80% capacity
  • Amber: 80-99% capacity (still functional, just means you may want to archive)
  • Red: Only shown for true errors, not for reaching documented limits

Login Issues

Can't Sign In

  1. Verify your email address is correct
  2. Check if you used social login (Google/GitHub) instead of password
  3. Try the "Forgot Password" flow
  4. Clear browser cache and cookies, then try again

Two-Factor Authentication Problems

  • Code not working: Check your device's time is accurate
  • Lost authenticator: Use a backup code
  • No backup codes: Contact support

Session Expiring

If you find yourself signed out frequently:

  1. Check that cookies aren't being cleared by your browser
  2. Ensure "Remember Me" is selected on sign in
  3. Check for browser extensions blocking cookies

Every API call returns 403, but login works

Symptom. POST /api/auth/login returns a token, and every call using that token answers:

403 {"code":"PASSWORD_CHANGE_REQUIRED","password_must_change":true}

Most often seen on a fresh self-hosted install, and most often by a script or an AI agent rather than by a person in the browser — because the browser shows a password-change screen, while a script just sees a 403 it cannot explain.

Cause. The account still carries password_must_change. On a fresh install the seeded owner always does, and POST /api/auth/login is deliberately outside that wall so the flag can be cleared at all. A valid token plus a 403 on everything else is the wall working, not a broken install.

Fix. Call POST /api/auth/change-password with currentPassword and a newPassword of at least 8 characters containing an uppercase letter, a lowercase letter and a digit. Your existing token keeps working afterwards — nothing is revoked.

Two different 403s, and only one has a code

A 403 with "code":"PASSWORD_CHANGE_REQUIRED" is the wall. A 403 from /api/auth/change-password without a code means the currentPassword you sent was wrong. Read the body, not the status — treating them as the same thing sends you looking for a permissions bug that does not exist.

Full sequence, including why the seed file disappears after a successful change and why the wall drops immediately rather than after the 15-second user cache: Self-hosting → If you are scripting the install.

Performance Issues

Slow Loading

  1. Close unused browser tabs
  2. Disable unused extensions
  3. Try the desktop app instead of browser
  4. Check your internet speed

High Memory Usage

  1. Limit the number of open notes
  2. Close browser tabs with Glassy open
  3. Restart the app periodically

Data Recovery

Accidentally Deleted a Note

  1. Check the Archive (Notes → Archived)
  2. Look in Trash (items stay for 30 days by default; Settings → data & backup → trash can keep them until you empty it)
  3. Contact support if the note isn't in either

How to Restore from Archive

  1. Go to your Notes list
  2. Find Archive in the sidebar
  3. Locate the note you want to restore
  4. Select it and choose Restore

Capture & Extension Issues

My capture didn't save

Use this decision tree to diagnose a missing capture:

  1. Is there a badge number on the extension icon?
  2. Yes → your capture is in the offline queue. Wait 60 seconds for an auto-flush, or check Settings → Debug → Offline Queue to see the error.

  3. No → proceed to step 2.

  4. Does the popup show a "Success" toast?

  5. Yes → the capture was accepted; search Glassy for the title or URL.

  6. No → check the browser console for CONTENT_SCRIPT_ERROR messages (right-click extension icon → Inspect background service worker).

  7. Is the page a PDF, browser-internal page (e.g. chrome://, about:), or a page with strict CSP?

  8. Yes → extractor.js cannot run on these. The capture will still proceed with URL and title, but the body will be empty. This is expected.

  9. Is the configured server URL correct?

  10. Open Settings → Server URL and verify it matches your Glassy instance (e.g. https://app.glassy.fyi).

  11. Still missing? Check server logs: 

    docker logs glassy-dash-prod | grep "POST /api/captures"
    A 500 here means the server accepted the request but encountered a DB error. Contact support with the log snippet.

Screenshot is broken or not embedded

Screenshots are uploaded as WebP to POST /api/ext/capture-image on your Glassy server. If the upload fails:

  • The capture text (title, URL, Markdown body) is still saved.
  • The screenshot embed will be absent from the capture.
  • The upload error is logged in the extension's service worker console.

Common causes and fixes:

Symptom Likely cause Fix
![Screenshot](broken-url) in capture Server was offline at capture time Re-capture when server is reachable
No screenshot section at all Smart capture wasn't expanded Tap ⚙ Smart capture to expand, then use the Screenshot button
Upload succeeds but image shows blank Browser screenshot permission denied Check activeTab and tabs permissions in chrome://extensions
Image URL points to wrong server Wrong server URL in Settings Update Settings → Server URL to your correct instance

Content script error badge

If the extension icon shows a small error indicator after a capture:

  1. Open the extension popup — the error message is shown inline.
  2. Common errors:
  3. "Cannot access page" — restricted URL (PDF, chrome:// pages, extension pages)
  4. "Readability parse failed" — the page had no detectable content body (login page, SPA loading state). Tags and URL are still captured.
  5. "Server unreachable" — capture is queued offline; see Offline Behavior.

Self-Hosted Appliance Issues

The page loads but is completely blank

Symptom. Your appliance answers HTTP 200, the container reports healthy, curl of the root path returns HTML — but the browser shows an empty page. Opening developer tools shows the console and network tabs full of 403 responses for /assets/*.js and /assets/*.css.

Cause. Builds before v2.40.2 decided "is this request from my own site?" by consulting a hardcoded list of allowed origins plus the socket address, and the socket check only ran when the request carried no Origin header. A production browser bundle is emitted with crossorigin, so it always sends Origin — which meant the allowlist was the only thing consulted, and it contained http://localhost, http://localhost:3000 and http://127.0.0.1:3001, but not the address you were actually using. The appliance was refusing to serve its own JavaScript.

This is why it only bites some installs: APP_PORT defaults to 3000, so the default localhost:3000 install was allowed by accident, not by design. It fails when you reach the appliance on:

  • a custom APP_PORT (http://localhost:3005)
  • a LAN address (http://192.168.1.20:3000)
  • a Tailscale hostname (http://box.tail-net.ts.net:3000)
  • your own domain (https://glassy.example.com)

Fix. Upgrade to v2.40.2 or later, which decides sameness from the Host header the browser derives from the URL it is fetching — so an appliance always serves its own bundle, and still refuses everyone else's.

# .env
GLASSY_TAG=v2.58.0

docker compose pull && docker compose up -d

Then close and reopen the tab. A service worker and CSP from the broken build can keep serving the stale shell after the container is fixed.

If you cannot upgrade yet, set CORS_ORIGINS to the exact origin you type into the browser — scheme, host and port, all three — and make APP_URL agree:

APP_PORT=3005
APP_URL=http://localhost:3005
CORS_ORIGINS=http://localhost:3005

All three must match the address in your address bar. CORS_ORIGINS is a comma-separated list, so a Tailscale or LAN install typically wants several:

CORS_ORIGINS=http://localhost:3000,http://192.168.1.20:3000,http://box.tail-net.ts.net:3000

How to confirm the diagnosis in one command — ask the appliance for its own bundle the way a browser does:

A=$(curl -s http://localhost:3005/ | grep -o '"/assets/[^"]*\.js"' | head -1 | tr -d '"')
curl -s -o /dev/null -w '%{http_code}\n' -H "Origin: http://localhost:3005" "http://localhost:3005$A"

200 means the appliance serves its own assets; 403 is this bug.

docker compose refuses to start and mentions GLASSY_TAG

GLASSY_TAG is required and has no default. The compose file uses ${GLASSY_TAG:?…}, which makes Docker refuse rather than silently pull :latest — because :latest is the hosted build and omits the self-host feature flags, so an appliance pointed at it hides MCP, the Second Brain, Agent connections and BYOK and shows a "You are on the cloud" banner on your own hardware. Set it to a released version tag and never to latest or main.

Getting More Help

If these solutions don't resolve your issue:

  1. Search the FAQ for specific topics (coming soon — see docs.glassy.fyi)
  2. Check the System Status for outages
  3. Contact support through the Help Center