WHEN SOMETHING GOES WRONG

Find the cause.
Fix it calmly.

Practical troubleshooting steps for setup, code, Git, deployments, and account issues. Start with the symptom that looks familiar.

Common problems, practical next steps

8 guides

SetupThe terminal says “node” or “npm” is not recognizedYou installed Node.js, but a new terminal cannot find the commands.

Close every open terminal window and open a new one so it reloads your system PATH.
Run node --version and npm --version to check whether both commands are available.
If they are still missing, reinstall Node.js from the official site and keep the installer’s PATH option enabled.
On macOS or Linux, check the official installation guidance for your shell before changing PATH manually.

SetupA development server says the port is already in useThe app cannot start because another process is listening on its local port.

Look for another terminal where a development server is still running.
Stop only the process you recognize with its normal keyboard interrupt, then restart your app.
If you need both apps open, use the alternate port offered by the development server.
Do not kill unrelated processes just to free a port.

CodeThe app says it cannot find a moduleA build or development command reports that a package or local file is missing.

Confirm the terminal is in the project folder that contains package.json.
For a package import, check that the package appears in the project dependencies and install it with the project’s package manager.
For a local import, verify the filename, capitalization, and relative path. Some deployment systems use case-sensitive paths.
Restart the development server after correcting the dependency or path.

GitGit rejects a push because the branch is behindThe remote branch contains commits that are not in your local branch.

Fetch the latest remote changes so you can inspect what changed.
Integrate the remote commits using your team’s normal merge or rebase workflow.
Resolve conflicts in the affected files and run the relevant checks.
Push again after the branch contains both sets of changes. Avoid force-pushing shared branches.

DeployA Vercel environment variable is undefinedThe app works locally but a deployment cannot read a required setting.

Check that the variable name matches exactly, including capitalization.
Confirm it is configured for the environment receiving the deployment: Development, Preview, or Production.
Create a new deployment after changing a variable; existing deployments keep their original environment snapshot.
Never paste secret values into browser code, screenshots, or source control.

AccountsSign-in succeeds but the app immediately signs me outThe browser returns to the login page after a successful authentication response.

Confirm the app uses the exact preview or production origin in its trusted-origin configuration.
Check that secure session cookies are enabled for HTTPS and that cross-site preview cookies use the correct same-site setting.
Reload the protected page after sign-in and inspect whether the session cookie is present.
Do not disable CSRF or origin checks to work around a cookie problem.

CodeThe page is blank after a code changeThe browser shows an empty page or a runtime error instead of the app.

Read the first error in the browser console; later errors may be consequences of it.
Check the development server output for the matching file and line number.
Undo or correct the smallest change that introduced the error, then let the app reload.
If the page still fails, capture the error message and the steps that reproduce it.

DeployA deployment fails even though it worked locallyThe production build reports an error that does not happen on your computer.

Read the first failing build step and note the file and line reported.
Check for imports that work only on a case-insensitive filesystem.
Verify that required environment variables exist in the deployment environment.
Reproduce the production build locally only after checking the project’s documented build command.