Se trabalhas com Next.js em Windows e tens o repositório dentro do OneDrive, mais cedo ou mais tarde podes cruzar-te com este clássico: EINVAL: invalid argument, readlink ao tentar iniciar o npm run dev.
Aconteceu comigo e resolvi com uma abordagem muito simples: identificar a causa real (bloqueios + links/symlinks estranhos em .next), limpar de forma segura e depois prevenir para não voltar a perder tempo.
## O que está realmente a acontecer
Quando o OneDrive está a sincronizar uma pasta de projeto, pode:
-
- bloquear ficheiros enquanto o Next compila
-
- “tocar” na metadata de ficheiros/pastas
-
- e, em alguns casos, deixar artefactos inconsistentes dentro de
.next(que é um diretório volátil e de alta rotação).
- e, em alguns casos, deixar artefactos inconsistentes dentro de
Resultado: O Next tenta fazer readlink (ler um link simbólico/junction) e o Windows devolve EINVAL.
## A minha revisão do plano (o que está correto e o que eu acrescentaria)
O teu plano base está correto e é minimalista:
- Terminar processos do Node para libertar bloqueios.
- Apagar
.next(artefactos corrompidos). - Apagar
tsconfig.tsbuildinfopara forçar uma recompilação limpa. - Verificar que o servidor de desenvolvimento chega a “Ready” e compila rotas.
O que eu acrescento para torná-lo “à prova de futuro”:
-
- Evitar que o OneDrive sincronize
.next(ideal) ou mover diretamente o repositório para fora do OneDrive.
- Evitar que o OneDrive sincronize
-
- Se precisares do OneDrive por política de empresa: pelo menos excluir a pasta do projeto ou usar uma localização local não sincronizada e sincronizar apenas documentos/exports.
-
- Se a equipa for grande: deixar um runbook (passos + comandos + critérios de sucesso) para que qualquer pessoa o possa executar.
## Passos exatos que utilizo para resolver
Objetivo: voltar a um estado determinístico antes de correr
dev.
### 1) Terminar processos que bloqueiam ficheiros
No Windows, o mais prático é fechar os terminais e terminar processos node.exe ativos.
### 2) Limpeza segura de artefactos
Eu apago:
-
.next/
-
tsconfig.tsbuildinfo(se existir)
### 3) Iniciar dev e confirmar “Ready”
O meu critério de sucesso não é “arrancou”, é ver o log com:
-
✓ Starting...
-
✓ Ready in Xs
-
- e que comece a compilar rotas sem voltar a cair em EINVAL.
## Evidência de verificação (o que espero ver)
Um exemplo típico de um “estado saudável” assemelha-se a isto:
```text
▲ Next.js 15.1.0
-
- Local: http://localhost:3000
✓ Starting...
✓ Ready in 7.4s
○ Compiling /src/middleware ... ✓ Compiled /src/middleware ... ○ Compiling /[locale]/contenidos ...
```
Com isso, para mim, o erro fica resolvido.
## Como evito que volte a acontecer
Se queres a minha recomendação direta e sem voltas:
-
- Não tenhas o repositório dentro do OneDrive (melhor opção).
-
- Se não podes evitar:
-
- Excluir .next da sincronização (se o teu OneDrive/TI o permitir)
-
- ou trabalhar numa pasta local não sincronizada e subir as alterações via Git como deve ser.
.next não é “código fonte”, é lixo útil: se o OneDrive interferir, quebra o teu ciclo de desenvolvimento.
## Se quiseres, deixo isto blindado contigo
Quando este tipo de erro aparece uma vez, costuma ser a ponta do icebergue: caminhos longos, watchers, permissões, cache corrompida, CI diferente do local, etc.
Se quiseres que deixe isto estável (local + CI) e com uma checklist reproduzível, pede-me um diagnóstico.
