Atlas

Appearance

Troubleshooting ​

The first stop when something is wrong. Skim the section that matches your symptom.

Login and account ​

"Invalid credentials" but I'm certain the password is right ​

  • Caps lock check — the username field is case-sensitive (operator_id, lowercase by convention).
  • Password manager autofill sometimes inserts a trailing space; click the field and press End to verify nothing is past the visible characters.
  • If 2FA is enabled, the code window is 30 seconds — wait for the next code to begin and try a fresh one.

"Please verify your email" loop ​

  • Check spam / promotions folders for the verification mail.
  • The verification link expires after 24 hours; from /login use Resend verification if available, or request a fresh registration with the same email.

Lost 2FA device ​

  • Use a recovery code at the 2FA prompt. They are single-use.
  • If recovery codes are also lost, the account is unrecoverable through self-service. Contact the operator of your Atlas instance.

"Session expired" mid-workflow ​

  • Your refresh token reached its hard limit. Sign in again — your watchlist, alerts, and saved screens are intact.
  • Frequent expirations usually mean clock skew on a self-hosted backend; verify NTP on the host.

Workspace and panels ​

Dashboard renders blank with the sidebar visible ​

  • Open the browser DevTools → Network tab; reload. If /api/me returns 401, your session expired (sign in again). If it returns 5xx, the backend is unreachable — check the backend logs.
  • A failed Cesium tile load (the globe) doesn't blank the dashboard, but a missing VITE_API_URL build var does. Confirm the build was run with the right env.

A panel is empty / "no data" ​

  • Confirm the data provider for that panel is configured. The Market panel needs EODHD_API_KEY; the Globe AIS layer needs MARINETRAFFIC_API_KEY. See API keys.
  • For symbols specifically: the symbol may not be indexed by the upstream provider. Try a different ticker to isolate.

Switching panels feels laggy ​

  • The first switch loads bundle chunks (route-based code splitting). Subsequent switches are instant.
  • For a sustained slowdown, check the browser console for a runaway re-render loop and refresh.

"Failed to fetch" toasts ​

  • The frontend cannot reach the backend. In dev, confirm the backend is running on the URL pointed at by VITE_API_URL (default http://127.0.0.1:8000). In prod, check the reverse proxy.

Globe ​

Pins are missing for a vessel/aircraft I expect to see ​

  • Layer might be off — check the AIS / ADS-B toggle in the right rail (v / a shortcuts).
  • Sub-bar filter might be too tight (Saved-only, name filter) — clear filters.
  • Coverage gap or transponder off — see Data delays & limits.

Globe is slow / dropping frames ​

  • Cesium prefers a discrete GPU. On integrated graphics with hundreds of pins, drop the layer with the most points or zoom in to cluster.
  • Browser hardware acceleration must be on — check browser settings.

"Cesium token invalid" overlay ​

  • VITE_CESIUM_ION_TOKEN is missing or stale. Get a fresh token from Cesium Ion and rebuild the frontend.

Market panel ​

Quote is permanently "delayed" ​

  • Free Finnhub tier delays some exchanges; the badge is correct. To get realtime, upgrade Finnhub or use a different exchange.
  • WebSocket might be offline — refresh and watch the header status indicator.

Fundamentals show "—" for many fields ​

  • EODHD coverage gap on emerging markets, micro-caps, or recently-IPO'd names. Try a major-exchange peer to confirm.

Chart shows a strange spike that disappears on reload ​

  • A single bad tick from upstream. EODHD typically corrects on the next pull; the cache TTL is short (~5 min for intraday).

Alerts ​

Alert created but never fires ​

  • Verify state in the alerts panel — tracking is normal (within 1% of trigger), inactive is paused.
  • For market-hours alerts, confirm the symbol's market is currently open.
  • For email delivery, check your spam folder and verify the address in Settings → Profile.

Alerts firing constantly on a closed position ​

  • They don't auto-prune. Disarm or delete from the alerts panel.

AI chat ​

Empty / generic responses with no panel context ​

  • The AI grounds in your active panel. Switch to or focus the panel you want it to read before asking.
  • News/transcript summaries silently truncate beyond the model's context window — narrow the screen or transcript section.

"AI is offline" ​

  • Backend cannot reach the configured model provider. Check backend logs for the AI route.

Symbol search returns nothing ​

  • Check the asset class pill (All / Equity / FX / Crypto / Commodity) — it's filtering.
  • Fuzzy name search needs ~3 characters; very short queries return only exact-prefix matches.

Subscription and billing ​

Plan upgraded in Stripe but Atlas still gates the feature ​

Stripe portal won't open ​

  • Pop-up blocked. Allow pop-ups for the Atlas origin and retry.

Self-hosted specifics ​

Backend won't boot — KeyError: SECRET_KEY ​

  • That env var is required. Generate a long random string and set it before the boot command.

Backend logs failed to connect to redis ​

  • REDIS_URL is wrong or Redis isn't up. The cache layer is required for rate limiting and session refresh — Atlas won't run without it.

Migrations fail mid-run ​

  • Don't manually edit the schema. Check the failed migration's SQL, fix the underlying problem (usually a manually-edited row), and re-run alembic upgrade head.

CORS errors in browser console for prod ​

  • The frontend's VITE_API_URL must match the backend's allowed origins. In a single-domain deploy, set both to relative paths or the same canonical hostname.

Still stuck ​

Open an issue with:

  • What you did.
  • What you expected.
  • What happened (with browser console + backend logs trimmed to the relevant ~30 lines).
  • Atlas version (from Changelog or /health endpoint).
  • Browser + OS.

For security-sensitive reports, follow the disclosure path in SECURITY.md and do not post a public issue.

Released under the project license. Public sources only — no proprietary or restricted data.

Atlas