# Troubleshooting Guide

Here are some common issues you might run into while developing or using the Scoreko desktop app, along with quick fixes.

## The app says the NodeCG runtime is incomplete
This usually means you haven't bundled the runtime yet.
- Run `npm run prepare:runtime` in the `scoreko-electron-dev` folder.
- If you haven't even installed the parent bundle, go up to the repository root and run `pnpm install` first.

## NodeCG is present but internal dependencies are missing
This happens if dependencies changed or the initial copy was interrupted.
- Re-run `npm run prepare:runtime` to get a fresh copy.
- If you're seeing SQLite errors when the app launches, you probably need to run `npm run rebuild:native` to compile it for Electron's V8 engine.

## "No read/write permissions on NodeCG"
In production, Scoreko runs NodeCG out of your AppData folder to ensure it has write access. During local development, it runs directly from the repo. 
If you see this permission error locally, another process probably has a file locked. Close any zombie Scoreko or Node processes and try `npm run start` again.

## Port 9090 is already in use
You have another instance of NodeCG (or another web server) running on port 9090.
- Find and kill the process using the port, or change `NODECG_PORT` in your `.env` file to something else (like 9091).
- You can use `npm run doctor` to quickly test port availability.

## Timeout while waiting for NodeCG
The app waits for the NodeCG HTTP server to respond. If it times out:
- Check your terminal output. NodeCG might be crashing or hanging on startup due to a bundle error.
- If your machine is just slow, you can increase `NODECG_STARTUP_TIMEOUT_MS` in the `.env` file.

## The app crashes immediately on a fresh install
Scoreko copies the runtime to `%AppData%\scoreko\nodecg` and relaunches itself on the very first run. 
If it gets stuck in a loop or fails immediately:
- Check if your antivirus or Windows Search Indexer is aggressively locking the files in AppData as they are being copied.
- Try running `npm run rebuild:native` and then repackaging the app with `npm run dist:win`.

## macOS builds are failing complaining about an icon
The `electron-builder` config explicitly looks for a Mac icon at `static/icons/icon.icns`. If you don't have one, generate it and place it there before running the macOS build.

## Auto-updates aren't triggering
If you published a new release on Gitea but the app ignores it:
- Double check that `static/updates.json` has `"enabled": true` before you build the installer.
- Ensure your `apiUrl` points exactly to the Gitea API: `http://gitea.../api/v1/repos/<owner>/<repo>/releases/latest`.
- The git tag you created (e.g., `v0.2.0`) must be semantically higher than the version currently in your `package.json`.
- Make sure the installer `.exe` you uploaded to Gitea actually matches the regex in `assetPattern` (default is `Scoreko-setup-.*\.exe$`).