Come ho risolto l'errore EINVAL: readlink in Next.js quando il progetto risiede in OneDrive

Se lavori con Next.js su Windows e hai il repository all'interno di OneDrive, prima o poi potresti incappare in questo classico: EINVAL: invalid argument, readlink quando provi ad avviare npm run dev.

È successo a me e l'ho risolto con un approccio molto semplice: identificare la causa reale (lock + strani link/symlink in .next), pulire in modo sicuro e poi prevenire per non perdere più tempo.

## Cosa sta succedendo in realtà

Quando OneDrive sta sincronizzando una cartella di progetto, può:

• • bloccare i file (lock) mentre Next sta compilando
• • “toccare” i metadati di file/cartelle
• • e, in alcuni casi, lasciare artefatti incoerenti all'interno di .next (che è una directory volatile e ad alto turnover).

Risultato: Next prova a eseguire un readlink (leggere un collegamento simbolico/junction) e Windows restituisce EINVAL.

## La mia revisione del piano (ciò che è giusto e ciò che aggiungerei)

Il tuo piano base è corretto e minimalista:

1. Uccidere i processi Node per rilasciare i lock.
2. Eliminare .next (artefatti corrotti).
3. Eliminare tsconfig.tsbuildinfo per forzare una ricompilazione pulita.
4. Verificare che il dev server raggiunga lo stato “Ready” e compili le rotte.

Cosa aggiungo per renderlo “a prova di futuro”:

• • Evitare che OneDrive sincronizzi .next (ideale) o spostare direttamente il repo fuori da OneDrive.
• • Se hai bisogno di OneDrive per policy aziendale: almeno escludere la cartella del progetto o usare una posizione locale non sincronizzata e sincronizzare solo doc/export.
• • Se il team è grande: lasciare un runbook (passaggi + comandi + criteri di successo) in modo che chiunque possa eseguirlo.

## I passaggi esatti che uso per risolverlo

Obiettivo: tornare a uno stato deterministico prima di eseguire dev.

### 1) Terminare i processi che bloccano i file

Su Windows, la cosa pratica è chiudere i terminali e uccidere i processi node.exe attivi.

### 2) Pulizia sicura degli artefatti

Elimino:

• • .next/
• • tsconfig.tsbuildinfo (se esiste)

### 3) Avviare dev e confermare “Ready”

Il mio criterio di successo non è “è partito”, è vedere il log con:

• • ✓ Starting...
• • ✓ Ready in Xs
• • e che inizi a compilare le rotte senza ricadere in EINVAL.

## Evidenza della verifica (cosa mi aspetto di vedere)

Un tipico esempio di “stato sano” si presenta così:

```text

▲ Next.js 15.1.0

• • Local: http://localhost:3000

✓ Starting...

✓ Ready in 7.4s

○ Compiling /src/middleware ... ✓ Compiled /src/middleware ... ○ Compiling /[locale]/contenidos ...

```

Con questo, per me, l'errore è risolto.

## Come evito che accada di nuovo

Se vuoi la mia raccomandazione diretta e senza fronzoli:

• 1. Non tenere il repo all'interno di OneDrive (opzione migliore).
• 2. Se non puoi evitarlo:
• • Escludere .next dalla sincronizzazione (se il tuo OneDrive/IT lo consente)
• • oppure lavorare in una cartella locale non sincronizzata e pushare i cambiamenti via Git come si deve.

.next non è “codice sorgente”, è spazzatura utile: se OneDrive interferisce, rompe il tuo ciclo di sviluppo.

## Se vuoi, posso renderlo blindato con te

Quando questo tipo di errore appare una volta, di solito è la punta dell'iceberg: path lunghi, watcher, permessi, cache corrotta, CI diverso dal locale, ecc.

Se vuoi che lo renda stabile (locale + CI) e con una checklist riproducibile, chiedimi una diagnosi con me.