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$).

2.9 KiB Raw Blame History