# How to Troubleshoot Token Usage in Egonex AI: First Run vs Incremental Updates

> Troubleshoot Egonex AI token usage errors. Learn why first run tokens differ from incremental updates and how to resolve 403 Forbidden issues with fresh URLs.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-20

---

**Egonex AI generates a one-time access token in [`vite.config.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/vite.config.ts) when you launch the development dashboard, requiring the `?token=` query parameter on every request; after incremental updates or server restarts, a new token invalidates previous URLs, causing 403 Forbidden errors until you use the freshly printed URL from the terminal.**

The **Egonex-AI/Understand-Anything** repository secures its development dashboard using a lightweight token-gating mechanism implemented directly in the Vite configuration. Understanding how this **access token** behaves during your initial setup versus after incremental code changes is essential to avoid authentication errors when visualizing knowledge graphs.

## How the Token System Works

### Token Generation in vite.config.ts

When you execute `pnpm dev:dashboard`, the Vite configuration file at **[`understand-anything-plugin/packages/dashboard/vite.config.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/vite.config.ts)** generates a cryptographically random string stored in the `ACCESS_TOKEN` variable. The server immediately prints a URL to the terminal that embeds this token:

```bash
🔑  Dashboard URL: http://127.0.0.1:5173/?token=9f7c2b1e6a...

```

This URL must be used exactly as printed, as the token is not persisted to disk or environment variables.

### Middleware Validation Logic

The same configuration file injects a middleware function that intercepts every HTTP request before Vite handles it. The validation logic checks the query string using `url.searchParams.get("token")` and compares it against the runtime `ACCESS_TOKEN` variable:

```typescript
if (url.searchParams.get("token") !== ACCESS_TOKEN) {
  sendJson(res, 403, { error: "Forbidden: missing or invalid token" });
  return;
}

```

If the values mismatch, the server returns a **403 Forbidden** response. This enforcement applies to all endpoints, including static file serving and the [`/file-content.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main//file-content.json) API that provides raw source data to the dashboard.

## First Run vs Incremental Updates

### Fresh Server Start (First Run)

During the first run of `pnpm dev:dashboard`, the system creates a brand-new `ACCESS_TOKEN`. If you attempt to access `http://127.0.0.1:5173/` without the `?token=` parameter, the middleware rejects the request with a 403 error. The dashboard UI displays a localized error message defined in **[`understand-anything-plugin/packages/dashboard/src/locales/en.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/locales/en.ts)** under the `tokenGate` key, prompting you to provide the correct URL from the terminal.

### Post-Update Restarts (Incremental Updates)

After you modify source code and restart the development server, **a new token is generated**. Browser tabs that were open with the previous token will suddenly receive 403 errors upon refresh because the `ACCESS_TOKEN` variable has changed in the new process. This is the most common source of confusion during incremental development cycles.

To resolve this, copy the new dashboard URL printed in the terminal after the restart, or manually update the `token` parameter in your browser’s address bar to match the new value.

### Hot Module Replacement (HMR) vs Full Restart

When Vite performs **Hot Module Replacement (HMR)** without a full server restart, the original `ACCESS_TOKEN` persists in memory, and existing browser tabs continue to function. However, if you terminate the process (`Ctrl+C`) and run `pnpm dev:dashboard` again, the token regenerates, breaking existing sessions.

## Troubleshooting Common Token Issues

- **Missing Query Parameter:** Ensure your URL includes `?token=` followed by the exact string printed in the terminal. Accessing the root path alone always returns 403.

- **Token Mismatch After Restart:** Each server instance generates a unique token. If you see 403 errors after updating code, you are likely using a stale URL from a previous session.

- **Multiple Terminal Instances:** Running two dashboard servers simultaneously creates two different `ACCESS_TOKEN` values. Requests will only succeed when sent to the server instance that generated the token in the URL.

- **Reverse Proxy Stripping:** If you run the dashboard behind NGINX or another proxy, ensure the configuration forwards the full query string. Stripping parameters removes the token, causing 403 errors on every request.

- **Browser Cache:** Clear your browser cache or open an incognito window to ensure you are not loading a stale HTML file that references outdated resource URLs.

## Implementation Examples

### Starting the Development Server

Run the following command from the repository root:

```bash
pnpm install
pnpm dev:dashboard

```

Wait for the terminal output showing the dashboard URL, then open that exact link in your browser.

### Handling Incremental Updates

After editing files such as [`src/utils/layout.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/utils/layout.ts) or [`src/components/GraphView.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/components/GraphView.tsx):

```bash

# Save your changes, then restart the server

pnpm dev:dashboard

```

Look for the new token in the terminal output:

```bash
🔑  Dashboard URL: http://127.0.0.1:5173/?token=3a8f9e2b...

```

Update your browser’s address bar to use this new token to avoid 403 errors.

### Configuring NGINX with Token Preservation

If proxying the dashboard, ensure the query string passes through:

```nginx
location / {
    proxy_pass http://localhost:5173;
    proxy_set_header Host $host;
    # Preserve the query string including ?token=

    proxy_set_header X-Original-URI $request_uri;
}

```

## Key Source Files

- **[`understand-anything-plugin/packages/dashboard/vite.config.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/vite.config.ts)** – Contains the `ACCESS_TOKEN` generation and the middleware validation logic using `sendJson()`.
- **[`understand-anything-plugin/packages/dashboard/src/locales/en.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/locales/en.ts)** – Defines the `tokenGate` error message displayed when authentication fails.
- **[`understand-anything-plugin/packages/dashboard/src/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/index.ts)** – Entry point that initializes the dashboard application and expects the token-validated environment.
- **[`README.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/README.md)** – Provides high-level setup instructions and the `pnpm dev:dashboard` command reference.

## Summary

- The dashboard generates a **one-time access token** in [`vite.config.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/vite.config.ts) at server startup.
- Every request must include the exact `?token=` value printed in the terminal.
- **Incremental updates** require a server restart, which generates a **new token** and invalidates old browser URLs.
- **403 Forbidden** errors almost always indicate a stale or missing token parameter.
- Reverse proxies must preserve query strings to allow token validation to function.

## Frequently Asked Questions

### Why does my dashboard return 403 after restarting the dev server?

The `ACCESS_TOKEN` variable is regenerated every time you run `pnpm dev:dashboard`. Your browser tabs from the previous session contain the old token value, which no longer matches the new server instance. Copy the fresh URL from the terminal to restore access.

### Can I disable the token gate for local development?

Yes, but it is not recommended for networks beyond localhost. Comment out the middleware check in [`understand-anything-plugin/packages/dashboard/vite.config.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/vite.config.ts) that calls `sendJson(res, 403, ...)` when the token mismatches. Re-enable this protection before exposing the server to any public interface.

### How do I resolve token issues when running behind a reverse proxy?

Ensure your proxy configuration forwards the full query string to the upstream Vite server. NGINX users should verify that `proxy_pass` includes the `$request_uri` or that explicit rules do not strip the `?token=` parameter. The middleware requires access to `url.searchParams.get("token")` to validate requests.

### Where is the access token stored persistently?

The token is **not stored persistently**. It exists only as a runtime variable (`ACCESS_TOKEN`) within the Node.js process running the Vite dev server. This ephemeral design ensures that each development session has a unique, unpredictable credential that expires when the process terminates.