Skip to content

Troubleshooting

This page covers common issues that may arise when using the admin panel and their solutions.

CORS Issues

If you encounter CORS issues when connecting to the API, make sure the API is configured to allow requests from the admin panel's origin.

API CORS Configuration

CORS_ORIGINS in app/core/config.py includes (among others):

  • http://localhost:3102 (Svelte admin dev server, host-mapped port)
  • http://localhost:8080 (production admin panel, local/manual testing)
  • https://tracker-admin.glimpse.technology / https://tracker-admin.staging.glimpse.technology (deployed admin panel)

When using credentials mode 'include' for cookies (the admin panel always sends credentials: "include"; see packages/tracker-shared/src/api/client.ts), the server cannot use a wildcard (*) for the Access-Control-Allow-Origin header. Instead, it must specify the exact origin.

Adding Additional Origins

If you need to add additional origins, update the CORS_ORIGINS list in app/core/config.py:

CORS_ORIGINS: List[str] = [
    "http://localhost:3102",
    "http://localhost:8080",
    "https://your-custom-domain.com",  # Add your custom domain here
]

Proxy Solution

In production, the admin panel uses nginx to proxy requests to the API, which avoids CORS issues entirely (same-origin requests from the browser's perspective). The nginx configuration is defined in tracker-admin-svelte/docker/nginx.conf.

Authentication Issues

If you encounter authentication issues, check the following:

JWT Secret Key

Make sure the API is configured with the correct secret key for JWT token generation and validation. The secret key is defined in app/core/config.py:

SECRET_KEY: str = os.getenv("SECRET_KEY", "your-secret-key-for-jwt")

Authorization Header Format

Make sure the admin panel is sending the token in the correct format in the Authorization header:

Authorization: Bearer <token>

This is handled automatically by request() in packages/tracker-shared/src/api/client.ts, which reads the stored access token and attaches this header unless the request is explicitly marked authenticated: false (used for login and password-reset endpoints).

Refresh Session Issues

The admin panel only attempts a refresh once, on app load (initializeAuth() in packages/tracker-shared/src/state/auth.ts calls refreshSession(), which hits GET /api/v1/auth/refresh-cookie). There is currently no automatic retry-on-401 or background proactive refresh while the app is open — if the access token expires mid-session, subsequent requests fail with a 401 until the user reloads the page or logs in again. If you encounter issues:

  1. Check browser console/network logs for failed requests to /api/v1/auth/refresh-cookie
  2. Verify that the refresh token cookie is being properly set by the API (it's an HttpOnly cookie, so it won't show up in document.cookie — check the Set-Cookie response header on login instead)
  3. Confirm the cookie is actually being sent on the refresh request (it requires the request to be same-origin or otherwise covered by credentials: "include", and the cookie's domain/secure attributes to match)

Login First Attempt Failure

If a login attempt fails unexpectedly, check that stale state isn't being carried over:

  1. Clear any existing token from local storage (localStorage.removeItem("token")) before retrying
  2. Check the network tab for the actual error returned by /api/v1/auth/login/json
  3. LoginForm.svelte (packages/tracker-shared/src/components/auth/LoginForm.svelte) shows a generic "Invalid email or password" message for any failure, so check the network response for the real cause

Client Filtering and Resource Access

If you encounter issues with resource access:

  1. Check the server logs for client filtering debug messages
  2. Verify that the user has the correct roles and client_list in the database
  3. Ensure the API's client filtering logic is functioning correctly for the endpoint in question
  4. Check the browser console/network tab for the actual request the admin panel sent (it calls the REST endpoints directly via tracker-shared/api/*, there is no intermediate data-provider layer to debug)

Admin-Only Access to the Admin Panel

The admin panel itself is gated on the admin role, not just on being authenticated. tracker-admin-svelte/src/routes/(app)/+layout.svelte checks $authState.user?.roles.includes("admin") and shows an "Access denied" screen (with a log-out button) to any authenticated non-admin user, rather than the app. manager/user roles exist in the system for tracker-frontend-svelte, but cannot use the admin panel at all — if a user reports being blocked from the admin panel, check their roles first before troubleshooting client filtering.

API Connection Issues

If the admin panel cannot connect to the API, check the following:

  1. Make sure the API is running and accessible at the configured URL
  2. Check that the API URL is correctly configured (VITE_API_URL in tracker-admin-svelte/.env, defaults to /api/v1)
  3. Verify that there are no network issues preventing the connection
  4. Check the browser console for any connection errors

API URL Configuration

In Docker Compose development, make sure the admin-svelte-dev service is running and its Vite dev server is proxying /api/v1 to the dev API container. The dev proxy is defined in compose.yml and tracker-admin-svelte/vite.config.ts.

If you are running the production image directly, check the API_URL environment variable. The container entrypoint rewrites the nginx upstream (__API_URL__ placeholder in tracker-admin-svelte/docker/nginx.conf) from that value before starting nginx.

Performance Issues

If the admin panel is slow or unresponsive, check the following:

Browser Performance

  1. Check the browser console for any performance warnings or errors
  2. Use the browser's performance tools to identify bottlenecks
  3. Consider using a more performant browser (Chrome or Firefox are recommended)

API Performance

  1. Check the API's performance monitoring tools for any issues
  2. Verify that the API's caching mechanisms are working correctly
  3. Consider optimizing API endpoints that are frequently used by the admin panel

Svelte Performance

Svelte 5's runes-based reactivity ($state, $derived) only recomputes and re-renders what actually changed, so most of the classic React perf pitfalls (unnecessary re-renders, needing memo/useMemo/useCallback) don't apply. If a view feels sluggish, look for:

  1. Expensive work inside a $derived that runs on every keystroke (for example, unbounded client-side filtering over a large in-memory array) — consider debouncing or pushing the filter to the API
  2. Large {#each} blocks without a keyed (item.id) expression, which forces full re-creation of list items instead of reordering existing ones

Form Validation Issues

If form validation is not working as expected, check the following:

  1. Verify that the form validation rules are correctly defined in the relevant editor modal (for example, UserEditorModal.svelte, ClientEditorModal.svelte)
  2. Check that the API's validation logic matches the frontend validation
  3. Ensure that validation errors are being properly displayed to the user (editor modals show an alert alert-error block with the error message)

Common Validation Issues

  • Required Fields: Make sure required fields are properly marked as required in both the frontend and backend
  • Field Types: Ensure that field types match between the frontend and backend (e.g., string vs. number)
  • Field Lengths: Verify that field length constraints are consistent between the frontend and backend
  • Custom Validation: Check that custom validation rules are correctly implemented and consistent

Data Display Issues

If data is not being displayed correctly, check the following:

  1. Verify that the API is returning the expected data
  2. Check that the frontend is correctly parsing and formatting the data
  3. Ensure that the data is being properly passed to the components that display it

Common Data Display Issues

  • Date Formatting: Make sure dates are being properly formatted for display
  • Number Formatting: Verify that numbers are being properly formatted (e.g., decimal places, thousands separators)
  • Empty Values: Check that empty or null values are being handled correctly
  • Relationship Data: Ensure that related data is being properly fetched and displayed

Browser Compatibility Issues

The admin panel is designed to work with modern browsers, but if you encounter compatibility issues, check the following:

  1. Verify that you're using a supported, up-to-date browser (Chrome, Firefox, Safari, or Edge)
  2. Check that your browser is up to date
  3. Consider using polyfills for features that may not be supported in older browsers

Known Browser Issues

  • Internet Explorer: The admin panel is not designed to work with Internet Explorer
  • Older Browsers: Some features may not work correctly in older browsers
  • Mobile Browsers: The admin panel's layout is responsive (see Customization) and usable on mobile, but the tracker move wheel and drag interactions are designed primarily for larger touch/pointer surfaces