Skip to content

Troubleshooting

Jump to bottom
Beat edited this page Aug 28, 2026 · 6 revisions

Troubleshooting

Quick fixes for common issues. Each section includes the symptom, cause, and fix.

Check your data directory first. The server prints Data directory: <path> on startup — that's where it reads config, cookies, browser profile, and access key. The default is the data/ folder at the project root, overridable with OMNIVOX_DATA_DIR. If things aren't where you expect, check for an override in:

  • Environment: echo $OMNIVOX_DATA_DIR
  • .env file in the project root
  • docker-compose.yml environment section

If it's set anywhere, that's where the server is reading/writing — not the default data/ folder.

Electron Auth App

Electron app won't start

Symptom: npm start in omnivox-connection/ fails or nothing happens.

Fix:

cd omnivox-connection
rm -rf node_modules
npm install
npm start

If you're on Linux and see GPU/display errors, make sure you have a desktop environment. The Electron app cannot run headless — it opens a real browser window.

Login page is blank or doesn't load

Symptom: The Electron window opens but shows a white/blank page.

Cause: Network issue, or Omnivox is down.

Fix: Check that you can access https://mobl.omnivox.ca in a regular browser. If Omnivox is up, try restarting the Electron app.

App never offers the files after logging in

Symptom: You logged in and see the Omnivox home page, but the app never offers cookies.json / config.json to save.

Cause: The app captures the session when Omnivox calls WebUI.SetDefaultPage internally. If the login flow changed or was interrupted, this command may not have fired.

Fix: Close the window and try again. Make sure you complete the full login — enter credentials, go through any verification steps, and wait for the main Omnivox portal to load.

Can't find the saved files

Symptom: You saved cookies.json and config.json but can't find them.

Cause: The app saves each file through a save dialog — they went wherever you chose (typically your Downloads folder).

Fix: Find them and move them into your data folder — the app does not place them there for you. See Setup — the data folder.

Server Startup

"Cookie file not found" or "Configuration file not found"

Symptom: Server crashes on npm start with one of these errors.

Cause: The session files aren't in the data folder — the connection app doesn't place them automatically; you save them yourself and move them there.

Fix:

  1. Run the Electron app, complete login, and save both files (see above)
  2. Place them in the data folder and verify: 
    ls data/cookies.json data/config.json
  3. If deploying to a remote server, copy the files into the server's data folder: 
    scp cookies.json config.json user@server:omnivox-mcp/data/
  4. Make sure OMNIVOX_DATA_DIR points at that folder (unset, the server uses data/ at the project root)

"Missing required configuration fields"

Symptom: Server crashes saying config.json is missing required fields.

Cause: The config.json file is corrupted or incomplete — usually from an interrupted auth session.

Fix: Re-run the Electron app:

npm run reset
cd omnivox-connection && npm start

Puppeteer fails to launch (Linux)

Symptom: Error mentioning missing shared libraries, libnss3, libatk, libgbm, etc.

Cause: Chromium needs system libraries that aren't installed.

Fix (Debian/Ubuntu):

sudo apt-get update && sudo apt-get install -y \
  ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 \
  libatk1.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0 \
  libnspr4 libnss3 libx11-xcb1 libxcomposite1 libxdamage1 \
  libxfixes3 libxrandr2 libxshmfence1 xdg-utils

The Dockerfile already includes these — this only affects native Linux installs.

Port already in use

Symptom: EADDRINUSE: address already in use :::3000

Fix: Either kill the existing process or use a different port:

PORT=3001 npm start

Session & Request Errors

Requests suddenly start failing

Symptom: Tools/endpoints that were working now return errors or empty data.

Cause: The Omnivox session expired. Sessions don't last forever — Omnivox may invalidate them after inactivity or periodically.

Fix: Re-authenticate:

npm run reset
cd omnivox-connection && npm start
# Log in, save cookies.json + config.json, close the window
# Place both files back into the data folder
cd .. && npm start

npm run reset clears the stale browser profile and session files from the data folder (it honors OMNIVOX_DATA_DIR), so the server starts fresh. The access key is cleared too — update clients with the new one after restart.

"Skytech is not defined" or timeout waiting for Skytech

Symptom: Server starts but hangs or errors with a timeout on the Skytech check.

Cause: The Omnivox page didn't load properly — usually a session issue or network problem.

Fix:

  1. Check your internet connection
  2. Verify Omnivox is accessible: https://mobl.omnivox.ca
  3. Re-authenticate with npm run reset + Electron app

Download links return 401 or 403

Symptom: URLs from get-document-link or get-assignment-file-link don't work.

Cause:

  • 401: The web token expired (tokens last 15 minutes). Generate a new link.
  • 403: MCP_SERVER_URL is not set or doesn't match the URL you're accessing. Download link tools require the server to be publicly accessible.

Cross-Machine Setup

Copied files but server still fails

Symptom: You copied cookies.json and config.json to the server but it still says files not found.

Cause: Files aren't in the directory the server actually reads.

Fix: The server reads the data folder from OMNIVOX_DATA_DIR, falling back to data/ at the project root. Put the files where the server looks:

mkdir -p data
cp cookies.json config.json data/
npm start

Permission denied on the data folder

Symptom: Server can't read or write the data folder.

Fix:

chmod 700 data
chmod 600 data/*.json

Docker

Container can't find cookies/config

Symptom: Container starts but crashes with "Cookie file not found."

Cause: The volume mount isn't mapping to a folder that has the session files.

Fix: The docker-compose.yml mounts the host data folder (from OMNIVOX_DATA_DIR, default ./data) into the container at /data/omnivox. Make sure the host folder has the auth files before starting:

ls data/cookies.json data/config.json
docker compose up --build

Chromium crashes inside container

Symptom: Puppeteer errors about sandbox or GPU.

Fix: The Dockerfile installs Chromium dependencies, but if you're using a custom base image, make sure the deps from the Dockerfile's apt-get install are present. Puppeteer runs with --no-sandbox in containers by default.

MCP Connection

MCP client can't connect

Symptom: Your MCP client (Claude Desktop, etc.) fails to connect to http://localhost:3000/mcp?key=....

Fix:

  1. Verify the server is running: curl http://localhost:3000/mcp?key=YOUR_KEY
  2. Check the access key matches <data folder>/accessKey.txt
  3. Make sure you're using the Streamable HTTP transport, not STDIO

Access key doesn't work

Symptom: 401 or 403 on every request.

Fix: The access key is in <data folder>/accessKey.txt. If you've run npm run reset, a new key is generated on the next server start — update your client config with the new key.

Still stuck?

Open an issue: https://github.com/Beat-YT/omnivox-mcp/issues

Clone this wiki locally