Troubleshooting

For setup-specific issues (won’t install, won’t start, can’t connect a bucket), see the troubleshooting sections in Installation and First Upload first. This page covers everything else.

Development

TypeScript errors that don’t match what’s in the file Restart the TS server: Cmd/Ctrl + Shift + P → “TypeScript: Restart TS Server” in VS Code. Next.js’s incremental type info can get stale.

Styling changes not showing up Restart pnpm dev:frontend. If that doesn’t help, delete the frontend .next/ cache and restart:

rm -rf frontend/.next
pnpm dev:frontend

Module resolution errors after pulling new changes

rm -rf node_modules
pnpm install

Run this from the repository root so PNPM can restore the whole workspace.

Linting and Formatting

Pre-commit hook fails lint-staged runs eslint --fix and Prettier on staged files automatically, but ESLint errors (not warnings) will still block the commit. Run:

pnpm lint
pnpm format

then re-stage and commit again.

A file you didn’t expect shows lint warnings on every change Check if it’s on the tracked debt list in eslint.config.mjs (see Coding Standards). Warnings there are expected until the underlying issue is fixed; they won’t block your commit unless you introduce a new one.

CI

A PR’s required check is stuck pending instead of pass/fail Check whether ci-ok in the Actions tab actually ran. If an earlier job failed to even start (a workflow syntax issue, usually), ci-ok never runs and the check sits pending indefinitely rather than failing outright. See CI/CD.

CI fails but the same commands pass locally Run the exact commands from CI/CD rather than pnpm dev:frontend-adjacent commands - a stale local .next/ cache or node_modules state is the usual cause of “works on my machine.”

Still Stuck?

Open an issue  with your OS, Node/pnpm versions, the exact command, and the full error output.