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 /it/docs/web/troubleshooting.md (or send Accept: text/markdown).
Risoluzione dei problemi
Diagnostica i problemi di installazione alla frontiera che è davvero fallita.
Installazione e configurazione
Prima di qualsiasi passaggio, leggere Prima di iniziare e Nozioni di base sui terminali. Queste istruzioni presuppongono che tu abbia aperto l'intero supastack monorepo in VS Code; la sua radice package.json contrassegna la radice del repository. Nei comandi pnpm, un pacchetto dell'area di lavoro è un'app o una cartella di codice condiviso; nel prodotto, uno spazio di lavoro è il contenitore dei dati di un team e il limite di sicurezza. corepack pnpm --filter ... seleziona un pacchetto dal monorepo mentre i comandi vengono eseguiti dalla sua radice. Se hai aperto solo una cartella mobile o desktop sincronizzata, non contiene il backend Web, la configurazione di Docker o gli script root: esegui il backend da questo monorepo o da un server ospitato raggiungibile e utilizza gli script della cartella della piattaforma. Una variabile di ambiente è un'impostazione denominata memorizzata in un file .env locale o nel dashboard dell'hosting; riavvia l'app pertinente dopo averla modificata e mantieni i segreti del server fuori dai valori NEXT_PUBLIC_ e EXPO_PUBLIC_.
1. Copia la prima riga di errore utile e il comando che l'ha generata; non incollare valori segreti.
2. Dalla root del repository eseguire corepack pnpm --filter @supastack/web typecheck per errori di tipo Web o corepack pnpm test per la suite automatizzata.
3. Per un problema con il browser, avviare Web con corepack pnpm --filter @supastack/web dev e riprodurlo in http://localhost:3000. Previsto: è possibile stabilire se l'errore è nella configurazione, nel codice, nel database, nel provider o nel browser prima di modificare le impostazioni.
Leggi il comando che fallisce e il primo errore rilevante prima di cambiare la configurazione. Determina se il fallimento è installazione delle dipendenze, compilazione, validazione dell'ambiente, accesso al database, dispatch del provider o comportamento del browser.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm --filter @supastack/web build
corepack pnpm testComandi da copiare
Segui i commenti per vedere in quale cartella viene eseguito un comando. Se due terminali sono etichettati, apri due finestre di terminale e mantieni il primo comando in esecuzione mentre usi il secondo.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm testErrori del primo avvio, decodificati
Il primo avvio fallisce in un piccolo insieme di modi. Fai corrispondere la prima riga di errore rossa a una riga — gli errori successivi sono di solito conseguenze del primo, quindi correggi quello in cima prima di ogni altra cosa.
| Sintomo | Causa probabile | Prima correzione |
|---|---|---|
| node, corepack o pnpm non è riconosciuto / command not found | Lo strumento non è installato, o il terminale era aperto prima che l'installazione finisse | Installalo (o riapri il terminale), poi riprova node --version |
| Nessun package.json trovato / ENOENT package.json | Il terminale è nella cartella sbagliata | Entra con cd nella radice del repository — la cartella che contiene package.json — e riprova |
| EADDRINUSE / la porta 3000 è già in uso | Un altro dev server tiene ancora la porta | Trova il terminale di quel server e premi Ctrl + C, poi riavvia |
| ECONNREFUSED verso localhost:5432 o un errore di connessione al database | Postgres non è in esecuzione | Esegui docker compose up -d postgres, aspetta che sia healthy, poi riprova |
| Errore di validazione env che nomina una chiave mancante | apps/web/.env.local manca o ha un valore richiesto vuoto | Copia la chiave nominata da .env.example, assegnale un valore, salva e riavvia il server |
| corepack o pnpm mancanti dopo corepack enable | Nessuno shim pnpm su PATH | Usa corepack pnpm ... direttamente — non ha mai bisogno di uno shim; su Windows usa corepack.cmd |
| PowerShell dice che uno script .ps1 non può essere eseguito / è bloccato | La policy degli script di PowerShell blocca lo shim | Usa la forma .cmd — corepack.cmd pnpm install — nessun cambio di policy necessario |
Flusso di implementazione
Per accesso API mancante, verifica che il server sia in esecuzione e che l'origin configurato corrisponda al client. Per scelte AI non disponibili, ispeziona AI_MODEL_POLICY e le righe di catalogo abilitate. Per un'attività con stato di coda incerto, usa il flusso di ripristino salvato invece di un'altra submission.
Per problemi di layout nel browser, ispeziona gli stili calcolati e riproduci il viewport esatto. I token del chrome di prodotto vivono in app-theme.css (pack da catalog.ts); il blocco del brand marketing vive in theme.css. Gli override dei componenti possono comunque vincere per specificità. Controlla il raggio renderizzato invece della sola dichiarazione del token.
Verifica e risoluzione dei problemi
Se la pagina è su :3001, apri :3000 per l'app Web; :3001 appartiene al server apps/docs separato. Se un test richiede l'accesso al database, utilizzare un database di sviluppo isolato e controllare entrambe le posizioni .env. Se persiste lo stesso errore, includere il comando e disinfettare la prima riga di errore quando si richiede assistenza; non disabilitare mai i controlli di accesso o stampare i segreti nei log.
Non risolvere un controllo fallito disattivando l'autorizzazione, loggando segreti o trattando controlli di infrastruttura saltati come riusciti. Cattura una piccola riproduzione e la configurazione non sensibile rilevante. Riesegui il controllo fallito dopo la correzione, poi i test di regressione interessati.