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 /nl/docs/tanstack/troubleshooting.md (or send Accept: text/markdown).
Probleemoplossing
Diagnosticeer setupproblemen bij de grens die daadwerkelijk faalde.
Setup en configuratie
Lees vóór elke stap Voordat u begint en Basisbeginselen van de terminal. Deze instructies gaan ervan uit dat je de volledige supastack monorepo in VS Code hebt geopend; zijn root package.json markeert de root van de repository. In pnpm-opdrachten is een werkruimtepakket een app of map met gedeelde code; in het product is een werkruimte de gegevenscontainer en de beveiligingsgrens van een team. corepack pnpm --filter ... selecteert één pakket uit de monorepo terwijl opdrachten vanuit de root worden uitgevoerd. Als u alleen een gesynchroniseerde mobiele map of desktopmap hebt geopend, bevat deze niet de webbackend, Docker-installatie of rootscripts: voer de backend uit vanaf deze monorepo of een bereikbare gehoste server en gebruik de eigen scripts van de platformmap. Een omgevingsvariabele is een benoemde instelling die is opgeslagen in een lokaal .env-bestand of op uw hostingdashboard; start de relevante app opnieuw nadat u deze hebt gewijzigd en houd servergeheimen buiten de NEXT_PUBLIC_- en EXPO_PUBLIC_-waarden.
1. Kopieer de eerste nuttige foutregel en de opdracht die deze heeft geproduceerd; plak geen geheime waarden.
2. Voer vanuit de root van de repository corepack pnpm --filter @supastack/web-tanstack typecheck for Web type fouten uit, of corepack pnpm test voor de geautomatiseerde suite.
3. Voor een browserprobleem start u Web met corepack pnpm --filter @supastack/web-tanstack dev en reproduceert u het op http://localhost:3000.. Verwacht: u kunt zien of de fout in de installatie, de code, de database, de provider of de browser zit voordat u de instellingen wijzigt.
Lees het falende commando en de eerste relevante fout voordat je configuratie wijzigt. Bepaal of de failure dependency-installatie, compilatie, environmentvalidatie, databasetoegang, providerdispatch of browsergedrag is.
corepack pnpm --filter @supastack/web-tanstack typecheck
corepack pnpm --filter @supastack/web-tanstack build
corepack pnpm testCommando's om te kopiëren
Volg de opmerkingen om te zien in welke map een opdracht wordt uitgevoerd. Als twee terminals zijn gelabeld, opent u twee terminalvensters en laat u de eerste opdracht draaien terwijl u de tweede gebruikt.
corepack pnpm --filter @supastack/web-tanstack typecheck
corepack pnpm testFouten bij de eerste run, ontcijferd
De eerste run faalt op een klein aantal manieren. Koppel de eerste rode foutregel aan een rij — latere fouten zijn meestal gevolgen van de eerste, dus los de bovenste op vóór al het andere.
| Symptoom | Waarschijnlijke oorzaak | Eerste oplossing |
|---|---|---|
| node, corepack of pnpm wordt niet herkend / command not found | Het programma is niet geïnstalleerd, of de terminal was al open voordat de installatie klaar was | Installeer het (of heropen de terminal) en probeer daarna node --version opnieuw |
| Geen package.json gevonden / ENOENT package.json | De terminal staat in de verkeerde map | cd naar de root van de repository — de map die package.json bevat — en probeer opnieuw |
| EADDRINUSE / poort 3000 is al in gebruik | Een andere devserver houdt de poort nog bezet | Zoek de terminal van die server en druk op Ctrl + C, start daarna opnieuw |
| ECONNREFUSED naar localhost:5432 of een databaseverbindingsfout | Postgres draait niet | Voer docker compose up -d postgres uit, wacht op healthy en probeer dan opnieuw |
| Env-validatiefout die een ontbrekende sleutel noemt | apps/web-tanstack/.env.local ontbreekt of heeft een lege verplichte waarde | Kopieer de genoemde sleutel uit .env.example, geef hem een waarde, sla op en herstart de server |
| corepack of pnpm ontbreekt na corepack enable | Er staat geen pnpm-shim op PATH | Gebruik corepack pnpm ... direct — dat heeft nooit een shim nodig; gebruik op Windows corepack.cmd |
| PowerShell zegt dat een .ps1-script niet kan draaien / is geblokkeerd | Het scriptbeleid van PowerShell blokkeert de shim | Gebruik de .cmd-vorm — corepack.cmd pnpm install — geen beleidswijziging nodig |
Implementatieworkflow
Verifieer bij ontbrekende API-toegang dat de server draait en de geconfigureerde origin overeenkomt met de client. Inspecteer bij niet-beschikbare AI-keuzes AI_MODEL_POLICY en ingeschakelde catalogusrijen. Gebruik bij een onzekere queued taak de opgeslagen recoveryflow in plaats van nog een submission te starten.
Inspecteer bij browserlayoutproblemen computed styles en reproduceer het exacte viewport. Productchrometokens leven in app-theme.css (packs uit catalog.ts); de marketingmerklock leeft in theme.css. Componentoverrides kunnen alsnog winnen via specificiteit. Check de gerenderde radius in plaats van alleen de tokendeclaratie.
Verificatie en probleemoplossing
Als de pagina op :3001 staat, open dan :3000 voor de webapp; :3001 behoort tot de afzonderlijke apps/docs-server. Als een test om databasetoegang vraagt, gebruik dan een geïsoleerde ontwikkelingsdatabase en controleer beide .env-locaties. Als dezelfde fout zich blijft voordoen, vermeld dan het commando en de opgeschoonde eerste foutregel wanneer u om hulp vraagt; schakel nooit toegangscontroles uit en druk nooit geheimen naar logboeken af.
Los een falende check niet op door autorisatie uit te schakelen, secrets te loggen of geskipte infrastructuurchecks als geslaagd te behandelen. Leg een kleine reproductie en de relevante niet-geheime configuratie vast. Draai de falende check na de fix opnieuw, daarna de getroffen regressietests.