Troubleshooting

Start with:

nanodev doctor

It checks git, Node.js, your login and whether NanoSite is reachable, and tells you what to fix. Add --verbose to any command to see the git and network calls it makes.

Messages like "Not logged in" or "Your login has expired" mean nanodev has no valid token.

nanodev login

You can see and revoke the devices you've logged in from in your NanoSite account settings. If you revoked a device, log in again on it.

Git asks for a password

nanodev login sets up git credentials for NanoSite, so plain git pull and git push shouldn't ask for a password. If git still asks:

Run nanodev login again. It refreshes the git credentials too.
Make sure you're in a linked project folder and that git remote -v points to NanoSite.
If another credential helper (for example one from an IDE) answers first with an old password, remove the saved NanoSite entry from it and try again.

Push rejected: lockfile can't install on Linux

The cloud installs your packages on Linux. Some packages ship a different build for each system, and a package-lock.json made on Windows or macOS can be missing the Linux one. The push is rejected so the cloud build doesn't fail later.

Fix: push with nanodev push. It adds the missing Linux entries to your lockfile before pushing. It only adds the Linux builds of packages you already have. Package versions never change.

If you push with plain git, the rejection message prints the exact command to run. Run it, commit the updated package-lock.json, and push again.

Don't delete package-lock.json to fix this. A new lockfile can upgrade packages you didn't mean to change.

Push rejected: you're behind

! [rejected]  main -> main (fetch first)

Someone (a teammate or the AI builder) pushed first. Get their changes, then push again:

nanodev pull
nanodev push

nanodev push does the pull for you, so you'll usually only see this with plain git. If the pull stops on a conflict, see Conflicts.

Push rejected by a project rule

The message names the rule and the file. The common ones:

Ignored or secret file: remove it from git with git rm --cached <file>, commit, and push. If the file is in an earlier commit you haven't pushed yet, redo those commits without it: git reset --soft origin/main, then git rm --cached <file> and commit again. Keep secrets out of the repository.
File too large: host the file on a CDN and use its URL.
Package not allowed: remove the package from package.json, or contact us to ask for it to be allowed.
Website needs a subscription: upgrade the plan in your account.

The full list, with the reasons, is in What the server rejects.

The dev server can't reach your store data

Pages load but products are missing, or the terminal shows errors for /api requests.

Run nanodev doctor to check your network and login.
Run nanodev dev from inside the linked project folder (the one with the .nanodev folder).
Behind a company proxy or VPN? Make sure it allows HTTPS to NanoSite.
If you're logged in to more than one NanoSite server, check which one with nanodev whoami.

Checkout requests are always refused in local dev. That's expected, not an error. Test checkout with nanodev preview.

Version mismatches

A newer template, Ecommerce SDK or store runtime: nothing is updated for you. To upgrade, follow Packages: change the version, test with nanodev dev and nanodev preview, then push.
nanodev itself is out of date: update it with:
```
npm install -g @nanosite/nanodev@beta
```
Your packages differ from the cloud's: run npm ci. It installs exactly what package-lock.json says, which is what the cloud builds. nanodev pull does this when the lockfile changes.
It works locally but not in the cloud: build a private preview. It runs in the same runtime as your live store, so it shows problems before you publish.

Still stuck?

Run the failing command again with --verbose and contact us with the output, or open an issue on GitHub (never paste a token).