For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /pt/docs/web/troubleshooting.md (or send Accept: text/markdown).
Resolução de problemas
Diagnostica problemas de instalação na fronteira que realmente falhou.
Instalação e configuração
Antes de qualquer etapa, leia Antes de começar e Noções básicas sobre terminal. Estas instruções presumem que você abriu o monorepo supastack completo no VS Code; sua raiz package.json marca a raiz do repositório. Nos comandos pnpm, um pacote de espaço de trabalho é um aplicativo ou uma pasta de código compartilhado; no produto, um espaço de trabalho é o contêiner de dados e o limite de segurança de uma equipe. corepack pnpm --filter ... seleciona um pacote do monorepo enquanto os comandos são executados a partir de sua raiz. Se você abriu apenas uma pasta móvel ou desktop sincronizada, ela não contém o back-end da Web, a configuração do Docker ou os scripts raiz: execute o back-end deste monorepo ou de um servidor hospedado acessível e use os próprios scripts da pasta da plataforma. Uma variável de ambiente é uma configuração nomeada armazenada em um arquivo .env local ou no painel de hospedagem; reinicie o aplicativo relevante após alterá-lo e mantenha os segredos do servidor fora dos valores NEXT_PUBLIC_ e EXPO_PUBLIC_.
1. Copie a primeira linha de erro útil e o comando que a produziu; não cole valores secretos.
2. Na raiz do repositório, execute corepack pnpm --filter @supastack/web typecheck para erros de tipo da Web ou corepack pnpm test para o conjunto automatizado.
3. Para um problema de navegador, inicie a Web com corepack pnpm --filter @supastack/web dev e reproduza-o em http://localhost:3000. Esperado: você pode saber se a falha está na configuração, no código, no banco de dados, no provedor ou no navegador antes de alterar as configurações.
Lê o comando que falha e o primeiro erro relevante antes de mudar configuração. Determina se a falha é instalação de dependências, compilação, validação de ambiente, acesso à base, dispatch de fornecedor ou comportamento do browser.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm --filter @supastack/web build
corepack pnpm testComandos para copiar
Siga os comentários para ver em qual pasta um comando é executado. Se dois terminais estiverem rotulados, abra duas janelas de terminal e mantenha o primeiro comando em execução enquanto usa o segundo.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm testErros da primeira execução, decodificados
A primeira execução falha de um pequeno conjunto de maneiras. Relacione a primeira linha de erro em vermelho a uma linha da tabela — os erros seguintes costumam ser consequência do primeiro, então corrija o do topo antes de qualquer outra coisa.
| Sintoma | Causa provável | Primeira correção |
|---|---|---|
| node, corepack ou pnpm não é reconhecido / comando não encontrado | A ferramenta não está instalada, ou o terminal já estava aberto quando a instalação terminou | Instale-a (ou reabra o terminal) e tente node --version de novo |
| Nenhum package.json encontrado / ENOENT package.json | O terminal está na pasta errada | Entre com cd na raiz do repositório — a pasta que contém package.json — e tente de novo |
| EADDRINUSE / a porta 3000 já está em uso | Outro servidor de desenvolvimento ainda ocupa a porta | Ache o terminal desse servidor, pressione Ctrl + C e inicie de novo |
| ECONNREFUSED para localhost:5432 ou erro de conexão com o banco | O Postgres não está em execução | Execute docker compose up -d postgres, espere o estado healthy e tente de novo |
| Erro de validação de ambiente citando uma chave ausente | apps/web/.env.local está faltando ou tem um valor obrigatório vazio | Copie a chave indicada de .env.example, dê-lhe um valor, salve e reinicie o servidor |
| corepack ou pnpm ausente depois de corepack enable | Nenhum shim do pnpm está no PATH | Use corepack pnpm ... diretamente — nunca precisa de shim; no Windows use corepack.cmd |
| O PowerShell diz que um script .ps1 não pode rodar / está bloqueado | A política de scripts do PowerShell bloqueia o shim | Use a forma .cmd — corepack.cmd pnpm install — sem mudar política nenhuma |
Fluxo de implementação
Para acesso à API em falta, verifica que o servidor está a correr e que o origin configurado corresponde ao cliente. Para escolhas de IA indisponíveis, inspeciona AI_MODEL_POLICY e as linhas de catálogo ativadas. Para uma tarefa com estado de fila incerto, usa o fluxo de recuperação guardado em vez de outra submissão.
Para problemas de layout no browser, inspeciona estilos calculados e reproduz o viewport exato. Os tokens de chrome de produto vivem em app-theme.css (packs de catalog.ts); o bloqueio de marca de marketing vive em theme.css. Overrides de componente podem ainda ganhar por especificidade. Verifica o raio renderizado em vez de apenas a declaração do token.
Verificação e resolução de problemas
Se a página estiver em :3001, abra :3000 para o aplicativo Web; :3001 pertence ao servidor apps/docs separado. Se um teste solicitar acesso ao banco de dados, use um banco de dados de desenvolvimento isolado e verifique os dois locais .env. Se o mesmo erro persistir, inclua o comando e limpe a primeira linha de erro ao pedir ajuda; nunca desative verificações de acesso ou imprima segredos em logs.
Não resolvas uma verificação falhada desativando autorização, registando segredos ou tratando verificações de infraestrutura ignoradas como bem-sucedidas. Captura uma reprodução pequena e a configuração não sensível relevante. Corre a verificação falhada de novo após a correção e depois os testes de regressão afetados.