scoreko-electron-dev/docs/troubleshooting.md

Troubleshooting

The packaged NodeCG runtime is incomplete

• Run npm run prepare:runtime from scoreko-electron-dev.
• If the parent bundle is not installed yet, run pnpm install from the repository root first.

NodeCG is present but internal dependencies are missing

• Recreate the runtime with npm run prepare:runtime.
• If native SQLite errors appear during launch, run npm run rebuild:native before packaging.

No read/write permissions on NodeCG

• Installed builds run NodeCG from the user's app data folder, so this usually means the local development copy is locked.
• Close any running Scoreko/NodeCG process and run npm run start again.

Port <PORT> is already in use

• Free the port or set NODECG_PORT in .env.
• Use npm run doctor to validate availability before startup.

Timeout while waiting for NodeCG

• Check the Electron/NodeCG output in the terminal.
• Increase NODECG_STARTUP_TIMEOUT_MS if the environment is slow.
• Recreate the runtime with npm run prepare:runtime if the bundle changed.

First launch after install fails

• Scoreko relaunches itself automatically after a fresh runtime install.
• If it still fails, check whether antivirus or file indexing is locking %AppData%\scoreko\nodecg.
• Rebuild the installer with npm run dist:win after running npm run rebuild:native.

macOS build fails because of icon

• The configuration expects static/icons/icon.icns.
• Create that file before running macOS packaging.

Updates do not appear

• Check that static/updates.json has "enabled": true before building the installer.
• The apiUrl must point to Gitea's latest release API: /api/v1/repos/<owner>/<repo>/releases/latest.
• The release tag must be newer than the installed package.json version, for example v0.2.0.
• The release must include an installer asset matching assetPattern, by default Scoreko-setup-.*\.exe$.