Problemen met mislukte builds oplossen

When an Orbit build fails, the deployment detail page gives you the full log plus a categorised failure summary and a suggested fix. This guide walks through reading that page, the failures Orbit…

Wanneer een Orbit-build mislukt, geeft de deploymentdetailpagina u het volledige logboek plus een gecategoriseerde foutensamenvatting en een voorgestelde oplossing. Deze gids helpt u bij het lezen van die pagina, de fouten die Orbit bij naam erkent, de fouten die het niet doet, en wat u moet doen wanneer een build succesvol is maar de site nog steeds niet klopt.

De fout lezen

Open uw project in Orbit.
Open het tabblad Deployments.
Klik op de deployment met status Failed.
Lees eerst de foutensamenvatting boven het logboek, vervolgens het logboek zelf.

Mislukte deployment met de gecategoriseerde foutensamenvatting

Orbit kent aan elke fout een categorie toe: Out of memory, Compile error, Test failure, Lint error, Install error, Network error, Timeout of Unknown error. De categorie vertelt u welk deel van de pipeline u moet bekijken voordat u een enkele logboekregel leest.

Er is ook een knop Get AI diagnosis. Deze leest de laatste 120 regels van het logboek samen met het gedetecteerde framework en de foutcategorie en geeft een verklaring in natuurlijke taal.

De diagnose is gelabeld als AI-generated, verify before acting. Behandel het als een zeer goede aanwijzing naar de juiste logboekregel, niet als een autoriteit over uw codebase. Lees de regel waarop het verwijst voordat u iets wijzigt.

Als de build nooit is gestart en vast zit op Queued, slaat u over naar het gedeelte over wachtrijbuilds hieronder.

Fouten die Orbit bij naam herkent

Deze worden samen met een specifieke voorgestelde oplossing op de deploymentpagina weergegeven.

Wat Orbit detecteert	Wat het betekent	Oplossing
Missing module	Een import verwijst naar een pakket dat niet is geïnstalleerd	Voeg het pakket toe aan `package.json` en commit het, of corrigeer de typo in het importpad
`ERESOLVE` conflict	npm kan een peer-afhankelijkheid niet vervullen	Los het conflict op in `package.json`, of voeg `--legacy-peer-deps` toe aan uw installatieopdracht in Settings
TypeScript error	Typecontrole mislukt tijdens de build	Corrigeer de vermelde fouten. Voor problemen met types van derden, `skipLibCheck: true` in `tsconfig.json`
Out of memory	De build heeft het RAM van de buildmachine overschreden	Voeg `NODE_OPTIONS=--max-old-space-size=2048` toe als omgevingsvariabele, of ga over naar een plan met een grotere buildmachine
Build disk full	De build heeft de schijf vol gemaakt	Zoek naar een onverwacht groot `node_modules` of artefact, of ga over naar een plan met een grotere buildschijf
Build timed out	De build heeft de limiet van 30 minuten bereikt	Schakel buildcache in, verkleinde bundlegrootte, of zoek wat zich ophangt
Package not found (404)	Een afhankelijkheid bestaat niet onder die naam of versie	Controleer `package.json` op een typo, of bevestig dat het pakket is gepubliceerd
ESLint errors	Lintfouten hebben de build geblokkeerd	Corrigeer ze, of stop ervoor dat linting de build doet mislukken in uw frameworkconfiguratie
Syntax error	Onparseerbare bron	Ontbrekende accolade, niet-gesloten tekenreeks, of syntaxis die uw Node-versie niet ondersteunt
File not found	Een waarnaar verwezen bestand bevindt zich niet in de repository	Bevestig dat het is committed en controleer de hoofdlettergebruik van het pad
Lockfile out of date	Het lockfile komt niet overeen met `package.json`	Voer uw pakketbeheerder lokaal in en commit het bijgewerkte lockfile

De lockfilemismatch is de meest voorkomende eerste-deploymentfout en de meest verwarrende, omdat deze nooit lokaal gebeurt. npm ci, yarn install --frozen-lockfile en pnpm install --frozen-lockfile weigeren door te gaan wanneer het lockfile niet overeenkomt met package.json. Genereer het lockfile lokaal opnieuw en commit het.

Veelvoorkomende fouten per fase

Afhankelijkheidsinstallatie mislukt

De fase Install is mislukt.

Verkeerde pakketbeheerder. Orbit kiest npm, yarn of pnpm op basis van uw lockfile. Als meer dan één lockfile is gecommit, kan de keuze niet degene zijn die u verwacht. Verwijder degene die u niet gebruikt, of stel Install command expliciet in Settings in.
Privéregister. Als een afhankelijkheid afkomstig is uit een privéregister, moet het verificatietoken beschikbaar zijn tijdens de build als een omgevingsvariabele, en uw .npmrc moet ernaar verwijzen.
Node.js-versiemismatch. Sommige pakketten vereisen een minimale Node-versie. Stel Node.js version in Settings in op het hoofdversienummer: 18, 20 of 22.
Onvoldoende geheugen bij een grote monorepo. Gebruik npm ci in plaats van npm install, en overweeg een plan met een grotere buildmachine.

Buildopdracht mislukt

De fase Build is mislukt.

TypeScript- of lintfouten. Orbit voert uw buildopdracht precies zoals geschreven uit. Als uw build lokaal mislukt, mislukt deze hier ook.
Omgevingsvariabele ontbreekt tijdens build. Een variabele die tijdens de build wordt gelezen, moet bestaan voordat de build wordt uitgevoerd, niet alleen tijdens runtime. Voeg deze toe op het tabblad Env vars en implementeer opnieuw. Een buildtijdvariabele die na een deployment is toegevoegd, is niet van toepassing op deze deployment.
Verkeerde basismap in een monorepo. Stel Root directory in Settings in op het pad van de app, bijvoorbeeld apps/web.

Build loopt vast

Builds worden afgebroken na 30 minuten aan wandkloktime op elk plan. Als de uwe consistent dicht in de buurt komt:

Controleer het logbestand op een proces dat wacht op invoer. Een build die een vraag stelt, is een build die vastloopt.
Vermijd --legacy-peer-deps op een grote afhankelijkheidsboom tenzij je het nodig hebt.
Zorg ervoor dat buildcache wordt gebruikt. De Liftoff- en Apex-plannen bevatten dit; de implementatiepagina toont Cache hit of Cold build.
Upgrade naar een plan met meer build vCPU. Zie Orbit Plan Limieten.

De Build Start Nooit

Een implementatie die vast staat op Queued wacht op een buildslot. De detailpagina toont je wachtrijpositie en hoeveel van je gelijktijdige buildslots in gebruik zijn, en start de build automatisch wanneer er een vrijkomt. Launch en Liftoff staan één gelijktijdige build toe; Apex staat er drie toe.

Je kunt alles zien wat in beweging is op je account bij Orbit, dan Queue.

Als een implementatie in de wachtrij staat met niets anders dat draait, wordt deze waarschijnlijk eerder vastgehouden dan in de wachtrij geplaatst. Controleer op:

Awaiting approval, als Require approval for production is ingeschakeld
Een deploy lock op het project
Een deploy freeze schedule die de huidige tijd of dag blokkeert
CI required checks die wachten op je pipeline
Require staging success before production die wacht op een staging-implementatie van dezelfde commit

De Build Is Volledig Overgeslagen

Als een push geen implementatie heeft opgeleverd, is deze waarschijnlijk opzettelijk gefilterd:

Ignored paths: elk bestand in de push kwam overeen met een patroon zoals *.md of docs/**
Branch ignore patterns: de branch kwam overeen met iets zoals dependabot/*
Root directory: niets in de push raakte de monorepo-subdirectory voor dit project
Branch previews uit, en de push was niet naar production of staging

Build Geslaagd, Maar de Site Is Fout

Een groene build en een verbroken site is bijna altijd een configuratieprobleem in plaats van een codeprobleem.

404 op elke pagina. De Output directory is fout: Orbit heeft een map gepubliceerd die niet je build-output is. Controleer wat je build daadwerkelijk schrijft. Veelvoorkomende waarden zijn dist, .next, out, build en .output.

404 alleen op dynamische routes. De app heeft een draaiende server nodig en wordt als statische bestanden geserveerd. Schakel Server mode in onder Settings in Runtime. Dit is vereist voor Next.js met SSR, Remix, Nuxt en alles wat geen statische export is.

Assets 404 na een implementatie, voor gebruikers die al op de site waren. Ze hebben de oude pagina geladen en vragen oude bundle-URL's aan die niet meer bestaan. Schakel Skew protection in onder Settings, waardoor de artefacten van de vorige build beschikbaar blijven voor een retentievenster nadat een nieuwe implementatie live gaat.

Omgevingsvariabele is niet gedefinieerd bij runtime. Bevestig dat het bereik van de variabele deze omgeving daadwerkelijk omvat, en dat de implementatie na de wijziging dateert. De implementatiedetailpagina geeft precies aan welke sleutels bij buildtijd zijn injecteerd en toont ze in vergelijking met je huidige configuratie.

Build-instellingen per framework staan in Uw buildopdracht en uitvoermap configureren.

Opnieuw Proberen

Op de pagina van de mislukte implementatie:

Retry build voert dezelfde commit opnieuw uit.
More retry options, dan Retry with cleared cache, verwijdert eerst de buildcache.

Je kunt Orbit ook voor jezelf opnieuw proberen. Build auto-retry onder Settings plaatst mislukte builds veroorzaakt door infrastructuurfouten zoals een netwerkfout of timeout opnieuw in de wachtrij, tot drie keer toe. Het probeert opzettelijk geen codefouten opnieuw, dus een compilatie-, lint- of testfout gaat nooit in een lus.

Opnieuw proberen met een gewiste cache verwijdert de gecachte node_modules voor de omgeving en kan niet ongedaan worden gemaakt. De volgende build daarna zal langzaam zijn. Dat is het doel, maar doe het niet reflexief op een groot monorepo.

Een Slechte Build Tegen Het Bereiken Van Gebruikers Tegenhouden

Als een implementatie al live is gegaan en iets heeft verbroken, voer een rollback uit in plaats van te proberen vooruit te repareren onder druk. Rollback bevordert een al gebouwd artefact en duurt seconden. Zie Een implementatie terugdraaien.

Om verdere implementaties tegen te houden terwijl je onderzoekt, klik je Lock deploys op het project. Push-geactiveerde implementaties worden dan overgeslagen totdat je ontgrendelt, terwijl handmatige implementaties nog steeds werken, zodat je de fix kunt uitleveren.

Je kunt Orbit dit ook automatisch laten doen: Auto-rollback on failure herstelt de laatst gezonde implementatie wanneer een productie-implementatie mislukt, en een Health check-pad herstelt het wanneer de nieuwe implementatie niet antwoordt met een 2xx binnen 15 seconden.

Nog Steeds Vast

Als het logbestand eenvoudig eindigt zonder foutbericht, is het buildproces hoogstwaarschijnlijk gestopt: onvoldoende geheugen, of de buildmachine werd teruggeëist. Probeer eenmaal opnieuw. Als het op dezelfde manier twee keer mislukt, open je een ticket via KPanel of e-mail support@kapsulehost.com en voeg je de implementatie-ID toe die op de detailpagina wordt weergegeven.