# Installation and runtime troubleshooting

Start with `npm run doctor`; use `-- --running` after starting the app. Correct the
reported cause, then rerun the failed step. Keep `.env.local`, private data, and the
credential key; do not erase them as a general repair.

| Symptom                                  | Check and repair                                                                                                                                                                                      |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Node/npm command not found               | Install Node with npm from the official source, reopen the terminal, and check the versions.                                                                                                          |
| SQLite unavailable / Node too old        | HyperSEO needs Node 22.13+. Confirm the terminal is using the intended Node executable; a Node 22 experimental warning alone is expected.                                                             |
| `npm ci` fails                           | Check network/registry access and the supplied package-lock.json. Keep pinned versions; do not delete the lockfile or use an arbitrary dependency upgrade.                                            |
| Worker cannot find `tsx`                 | Run `npm ci --include=dev`. The local runner needs development dependencies even when using the built app.                                                                                            |
| `.env.local` invalid                     | Use literal values; `HYPERSEO_ORIGIN=http://127.0.0.1:PORT`, no path/query, port 1024–65535. Storage overrides must be private absolute paths outside source. Diagnostics never print invalid values. |
| Port already in use                      | Preserve the other app. Stop only your own runner or set an available port in `.env.local`, restart, and update Google redirects.                                                                     |
| `npm start` cannot find a build          | Run setup or `npm run build` first. A Next dev build is not the production build.                                                                                                                     |
| Browser responds but worker offline      | Start with `npm start` or `npm run dev`, not a bare Next command. Check both process logs. They must share the same origin and data folder.                                                           |
| Worker doesn't use a changed environment | Stop/restart the runner. Existing terminal environment variables override `.env.local`; inspect names privately, never dump all values.                                                               |
| Google callback fails                    | Use the configured canonical address; register the exact callback from Connections. Check enabled APIs, test-user access, consent scopes, and property matching.                                      |
| Old credentials cannot decrypt           | Restore the database's matching `credential.key` from your private backup. Do not generate a replacement key for an existing database.                                                                |
| WordPress change needs verification      | Inspect theme/SEO-plugin output and caches, then use Verify HTML. Do not automatically resend an uncertain write. Contract tests are not live rendering tests.                                        |
| Audit/job pending after restart          | Let the 90-second expired lease reconcile interrupted reads. Only two total attempts are allowed; failed jobs can be retried manually.                                                                |
| Recurring check delayed                  | Keep the computer awake and worker running. Queue capacity is 50 active jobs; existing jobs continue while schedules wait. Missing intervals collapse into one catch-up.                              |
| Fix remains unverified                   | Check the original page, required related URLs, robots/redirects/errors, and actual HTML. Incomplete coverage cannot prove resolution.                                                                |
| Release command refuses to package       | Review/commit source and start from a clean checkout. Private/unexpected tracked paths and symlinks intentionally stop packaging.                                                                     |

For a local support report:

```bash
npm run doctor -- --running --json
```

The script does not upload anything or print stored provider credentials. Review
its output before sharing. Optional Google/WordPress connectivity still needs
separate live acceptance checks.