> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 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](https://supastack.dev/pt/docs/web/before-you-start.md) e [Noções básicas sobre terminal](https://supastack.dev/pt/docs/web/terminal-basics.md). 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 test
```


## Comandos 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 test
```


## Erros 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.


## Seguinte

[Como usar esta documentação](https://supastack.dev/pt/docs/web/using-the-docs.md)