Troubleshooting

Work out whether the build, the deployment or the running Function failed, then read the log that covers that stage.

A failure in Gigadrive Network comes from one of three places: the build, the deployment that follows it, or the Function once it is live. The deployment's status tells you which one before you read a single log line.

Check the status page first

Before you debug your own deployment, rule out a platform-wide problem. gigadrivestatus.com shows the current status of each part of Gigadrive Network and lists any open incident.

Which one failed

What the console shows	Where it failed	What to read
Building, then Failed	Build	The deployment's Logs tab
Deploying or Waiting for capacity, then Failed	Deployment	The deployment's Logs tab, and Overview for a capacity wait
Ready, but requests return errors or hang	Runtime	The environment's Logs page
Ready, but a URL still serves the previous build	Deployment	The deployment's Overview tab, under Domains

Deploying is the console's label for provisioning, so a deployment that fails there built successfully. The artifact exists and the problem is in publishing it. Ready means the aliases have moved and the deployment is serving traffic, so every failure after that point is a runtime question, including a 500.

One nuance the table hides: packaging runs at the tail of the Building stage. A failure that names a missing entrypoint or an oversized artifact is a deployment problem that happened while the status still said Building.

The two logs never overlap. The deployment log holds build and provisioning output and stops when the deployment goes Ready. Runtime logs hold what your code writes to standard output and standard error, and they start at that same point.

A failed deployment does not take your site down

Aliases move in the publication step, which runs after provisioning succeeds. A deployment that fails during the build or while provisioning never becomes the one that serves traffic, so your production URL keeps serving the last deployment that reached Ready.

Reading a deployment log

Each stage of the deployment brackets its own name, so the failing stage is the last bracketed line in the log. In order: preflight-config, load-deployment-context, prepare-git-credentials, set-status-building, build-and-package, set-status-provisioning, provision-and-publish, publish-deployment-aliases, set-status-active.

A failure writes three things: the bracketed stage line, a short label, and then the message you can act on.

Detected pnpm, running pnpm install...
Running build script...
[build-and-package] Build and packaging failed
Build failed
Code failed with exit code 1

Two things about that output surprise people. Everything your build writes to standard error is recorded at error level, so red lines are common in builds that succeed. And any environment variable marked sensitive is replaced with *** wherever its value appears in the output, which is why a config dump can print masked values you did set.

Fetching a log outside the console

The credential needs the network:deployments:read scope. Logs come back in chronological order, at most 100 entries per page, and createdAt[gt] tails a running build without refetching what you already have.

import { GigadriveClient } from '@gigadrive/sdk';

const client = new GigadriveClient({
  clientId: process.env.GIGADRIVE_CLIENT_ID,
  clientSecret: process.env.GIGADRIVE_CLIENT_SECRET,
});

const page = await client.deployments.getLogs('0197b2f1-2f4a-7a0b-8a2d-222222222222', { limit: 100 });

for (const entry of page.items) {
  console.log(`${entry.createdAt} [${entry.type}] ${entry.message}`);
}

The three failure classes

Build failures

Detection, root directory, lockfiles, a build command that exits non-zero, memory, and native dependencies.

Deployment errors

What can still fail after a successful build: missing entrypoints, packaging, provisioning, capacity waits, and aliases.

Function errors

Timeouts, memory exhaustion, cold starts, unhandled exceptions, and how to tell them apart from a runtime log.