# 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.