← ./articles

Do Not Start Environment-Dependent Bugs with a Code Fix

debuggingwindowsnodejsnextjsworkflow

When a development command fails, it is tempting to start editing code.

That is not always the right first move. On Windows, especially with OneDrive, Node.js, and Next.js, failures often come from the execution environment rather than the application source: inherited environment variables, synced directories, editor type resolution, or concurrent builds.

For environment-dependent bugs, start by proving the layer that is failing.

Common environment-dependent symptoms

These failures often look like code bugs at first:

  • next build passes but next dev fails on valid CSS
  • tsc passes but VS Code reports missing Node globals
  • npm install --save-dev succeeds but the package is missing
  • a build prints success output and then exits non-zero
  • .next/routes-manifest.json suddenly cannot be found

All of these can be caused by the surrounding environment. If you fix code before checking that, you may change a working implementation for the wrong reason.

If you already know the symptom, start with the narrower article. For next dev CSS failures, see Why only next dev breaks CSS: it was NODE_ENV=production. For missing devDependencies after npm install --save-dev, see npm install Skips devDependencies? Check NODE_ENV=production. For missing .next/routes-manifest.json, see Next.js routes-manifest.json Missing? Check for Parallel next build First.

Record the exact reproduction context first

Before changing files, capture the context:

Command:
Working directory:
Shell:
Node version:
npm version:
NODE_ENV:
OneDrive path:
Error output:

On PowerShell:

$env:NODE_ENV
node -v
npm -v
Get-Location

The shell matters. PowerShell, Git Bash, and cmd handle quoting and variable expansion differently. The working directory matters too, especially when the project lives under a OneDrive-synced path.

If only one path fails, compare environments

When one command passes and another fails, do not assume the source code is inconsistent.

Example:

next build: pass
next dev: fail

or:

npx tsc --noEmit: pass
VS Code Problems: fail

Compare the failing and passing paths:

  • Are they reading the same config?
  • Are they inheriting the same environment variables?
  • Are they using the same TypeScript version?
  • Are they writing to the same build directory?
  • Is OneDrive syncing the files being written?

Do not edit code until the difference is known.

Avoid concurrent build artifact writes

Multiple terminals or multiple AI agents can accidentally run the same build at the same time.

That is dangerous. Next.js writes to .next/. Vite writes to dist/. Rust writes to target/. If two processes clean and write the same artifact directory concurrently, one process can observe missing or half-written files from the other.

The symptom may look like this:

Cannot find module '.next/routes-manifest.json'

If this was caused by parallel builds, changing Next.js config will not fix it. Confirm by running one clean build:

Remove-Item -Recurse .next, out
npm run build

Only remove known build output directories inside the project. Do not run recursive deletes on broad or computed paths.

Check OneDrive write paths

If the project is under OneDrive, inspect where high-frequency writes happen.

Check:

  • Is node_modules directly inside the synced folder?
  • Is it moved outside OneDrive with a junction?
  • Is .next, dist, or another build output being synced while builds run?
  • Did an old output directory remain after a failed build?

The presence of a dist or out directory does not prove the latest build succeeded. Verify freshness after failures.

If node_modules is part of the failure in a OneDrive-synced project, also check Node.js on OneDrive: Move node_modules with a Windows Junction. That article covers the narrower dependency-directory failure mode.

Change code only after isolating the layer

A reliable order is:

  1. Save the exact error output.
  2. Record command, shell, environment variables, and working directory.
  3. Compare the passing and failing paths.
  4. Exclude build artifact races and sync interference.
  5. Create a minimal reproduction if the source code still looks responsible.
  6. Make the smallest code change that addresses the confirmed cause.

This keeps the fix proportional to the real problem.

How to ask an AI agent to investigate

For environment-sensitive failures, ask the agent to investigate before editing:

next dev fails with a CSS parse error, but next build passes.
Do not change code first. Check environment variables, Next.js config, and dev/build differences.
Report the cause and verification command before applying any fix.

That prompt prevents the agent from rewriting CSS, PostCSS, or bundler config before checking the runtime environment.

Summary

Environment-dependent bugs should not start with code edits.

When a failure appears only in one command, one shell, one machine, or one build sequence, check environment variables, shell behavior, OneDrive, editor tooling, and build artifact races first. Once the failing layer is known, the actual fix is usually much smaller.