# SC001: Port already in use

> SC001 (port already in use) means something answered on the configured port before shutdown-check launched your service. Find what holds it and fix it.

Source: https://shutdown.jscrate.dev/docs/codes/sc001
Last updated: 2026-09-23

`SC001` means the port in `baseUrl` was not free before startup. shutdown-check
stops because it cannot separate your service from the process that is already
listening.

| | |
| --- | --- |
| Code | `SC001` (FAIL) |
| Stage | Before launch |
| CLI exit code | 1 |
| What it means | Something already answered on the configured port before the service was launched, so the check could not tell your service apart from it. |
| Message | `The local port at <origin> is already occupied or cannot be confirmed free; use a dedicated port` |
| First thing to check | Give the test a dedicated port, and stop any dev server or earlier run still listening on it. |

## Why does it happen?

- A development server is still running.
- Another test uses the same port.
- Parallel CI jobs share one `baseUrl`.
- The configured port belongs to a database, proxy, or service container.
- A previous run left a child process alive.

## How do I fix it?

1. Stop the process that owns the port.
2. Give shutdown-check a port reserved for this test.
3. Pass the same port to the service through `env`.
4. Give parallel tests different ports.

```json title="shutdown-check.json"
{
  "env": { "PORT": "3510" },
  "baseUrl": "http://127.0.0.1:3510"
}
```

If the problem appears after a previous test, check for a launcher that exits
without stopping its child server. That later failure is reported as
[SC302](https://shutdown.jscrate.dev/docs/codes/sc302).

## How do I verify the fix?

Run the same command again. The first timeline event should now be
`process launched`, not `check failed — SC001`. If the service then fails to
become ready, continue with SC100 or SC101; the port conflict itself is gone.

When the failure occurs only in CI, inspect parallel jobs and service
containers. A locally free port can still be shared on the runner.

## Related

- [Configure `baseUrl` and `env`](https://shutdown.jscrate.dev/docs/configuration#baseurl)
- [Give tests separate ports](https://shutdown.jscrate.dev/docs/guides/test-runners#give-every-test-its-own-port)
- [SC302: Port still open after exit](https://shutdown.jscrate.dev/docs/codes/sc302)