# How to Troubleshoot Astryx Build Errors: A Complete Developer Guide

> Fix Astryx build errors fast. This guide details steps for Node version checks, workspace cleaning, type validation, StyleX output, and debug logging to resolve issues.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-08-03

---

**The most effective way to troubleshoot Astryx build errors is to systematically check the Node version, clean the workspace, run type checks across all packages, validate StyleX output, and use debug logging to isolate the failing layer.**

Astryx is a Facebook open-source monorepo that uses **pnpm workspaces**, **TypeScript**, **Vitest**, and **StyleX** to build a design-system library and accompanying tooling. Build failures typically originate from one of six distinct layers, and understanding how to diagnose each layer will save hours of debugging time.

## Recognize the Error Layer

Build failures in Astryx fall into predictable categories. Identifying which layer produces your error message is the first step toward resolution.

### Package Manager Errors

**pnpm workspace resolution** is the foundation of Astryx. When this layer fails, you'll see messages like `ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL` or missing lockfile warnings.

These errors live in [`pnpm-workspace.yaml`](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml), [`pnpm-lock.yaml`](https://github.com/facebook/astryx/blob/main/pnpm-lock.yaml), and each package's [`package.json`](https://github.com/facebook/astryx/blob/main/package.json). Run this diagnostic:

```bash
pnpm install --frozen-lockfile

```

Inspect the output for "cannot resolve" messages that indicate which workspace package cannot find its dependency.

### TypeScript Compilation Errors

**Type-checking failures** appear as `TS2307: Cannot find module …` or mismatched `tsconfig` settings across packages. The source configuration lives in [`tsconfig.json`](https://github.com/facebook/astryx/blob/main/tsconfig.json) and each package's `tsconfig.*.json`.

Run the workspace-wide type check to isolate the first error (subsequent errors usually cascade from it):

```bash
pnpm -r exec -- tsc --noEmit

```

This command compiles every workspace package in isolation and reports exact file paths and line numbers.

### StyleX Generation Failures

**CSS-in-JS compilation** fails with `stylex: unknown token` or runtime `ReferenceError` for generated CSS. The StyleX definitions reside in `packages/*/src/**/*.stylex.ts` and the scanner logic is in `internal/stylex-capabilities/scan.mjs`.

Re-run the StyleX validator to catch missing markers:

```bash
pnpm run verify-exports

```

This executes `scripts/verify-exports.mjs`, which checks that every exported component has corresponding StyleX definitions.

### Vitest Test Suite Failures

**Test runner errors** manifest as `ERR_MODULE_NOT_FOUND`, snapshot mismatches, or CI hangs. Configuration lives in [`vitest.config.ts`](https://github.com/facebook/astryx/blob/main/vitest.config.ts) and `vitest.global-setup.node.mjs`.

Execute tests locally to capture the full stack trace:

```bash
pnpm test

```

The stack trace will point directly to the offending import or mock configuration.

### CLI and Build Script Errors

**Build script failures** occur when running `$ASTRYX build`, showing `node:internal/modules/cjs/loader: Cannot find module …`. The entry point is `packages/cli/clients/cli/bin/astryx.mjs` with supporting scripts in `scripts/`.

Enable verbose debug logging:

```bash
DEBUG=astryx:* pnpm build

```

This output shows precisely which package is being processed when the error occurs.

### Environment and Node Version Errors

**Runtime syntax errors** like `SyntaxError: Unexpected token …` for optional-chaining indicate Node version mismatches. The required version is specified in `.nvmrc` (currently **v20**).

Verify your environment:

```bash
node -v
cat .nvmrc

```

## Follow the Systematic Troubleshooting Workflow

This sequence isolates build errors from most to least frequent causes.

### Step 1: Verify Node Runtime

Mismatched Node versions cause syntax errors in modern TypeScript output. Check the specification and switch versions:

```bash
nvm use $(cat .nvmrc)

```

### Step 2: Clean the Workspace

Stale caches create phantom module-resolution failures:

```bash
pnpm clean && pnpm install --frozen-lockfile

```

### Step 3: Run Workspace-Wide Type Check

```bash
pnpm -r exec -- tsc --noEmit

```

Fix the first error reported; later errors typically cascade from it.

### Step 4: Execute StyleX Validation

```bash
pnpm run verify-exports

```

This validates that every exported component in `packages/core/src/stylex/` has proper marker definitions.

### Step 5: Build the Library

```bash
pnpm build

```

If this fails, the console shows which package script (`packages/<pkg>/scripts/build.mjs`) exited with non-zero status. Examine that script to see the exact build command—typically `vite build` or `rollup`.

### Step 6: Run the Test Suite

```bash
pnpm test

```

Failing tests often reveal regressions that broke the build. Watch for `expect(...).toMatchSnapshot()` mismatches.

### Step 7: Consult Release Documentation

The [`docs/release.md`](https://github.com/facebook/astryx/blob/main/docs/release.md) file contains the exact sequence of steps that CI uses. Compare your local steps against this reference to identify deviations.

## Fix Common Error Messages

| Error | Cause | Solution |
|-------|-------|----------|
| `ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL` | Workspace package `prepare` script failure | Delete `node_modules` in the offending package: `pnpm -C packages/<pkg> remove node_modules` then reinstall |
| `TS2307: Cannot find module '@astryxdesign/core'` | Core package not built before dependent import | Run `pnpm -r exec -- pnpm build` starting with `@astryxdesign/core` (order defined in [`pnpm-workspace.yaml`](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml)) |
| `stylex: unknown token "var(--astryx-color-primary)"` | Missing CSS variable definition | Add to [`packages/core/src/theme/vars.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/vars.stylex.ts) and re-run `pnpm stylex:scan` |
| `ReferenceError: process is not defined` | Node globals in browser build | Guard with `if (typeof process !== 'undefined')` or move to server-only module |
| `Vitest: Could not resolve import …` | Path alias (`~`) misconfigured | Add alias in [`vitest.config.ts`](https://github.com/facebook/astryx/blob/main/vitest.config.ts) under `test: { resolve: { alias: { '~': path.resolve(__dirname, 'src') } } }` |

## Essential Commands for CI Debugging

```bash

# Re-install exact versions

pnpm install --frozen-lockfile

# Full type-check across workspaces

pnpm -r exec -- tsc --noEmit

# Validate StyleX output

pnpm run verify-exports

# Build everything (skip verification)

pnpm -r run build --no-verify

# Run specific failing test

pnpm test -- <test-file>

```

## Key Source Files for Deep Debugging

- **[`pnpm-workspace.yaml`](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml)** — Declares workspace packages and dependency order
- **`scripts/verify-exports.mjs`** — StyleX scanner and export validation
- **[`vitest.config.ts`](https://github.com/facebook/astryx/blob/main/vitest.config.ts)** — Test runner configuration with path aliasing
- **`packages/cli/clients/cli/bin/astryx.mjs`** — CLI entry point for build commands
- **`packages/core/src/stylex/`** — StyleX marker definitions and theme variables

## Summary

- **Always verify Node version** against `.nvmrc` before any other debugging step
- **Clean installs** with `--frozen-lockfile` eliminate most package manager issues
- **Type-check first** with `tsc --noEmit` to find root-cause errors before cascading failures
- **StyleX validation** via `verify-exports` catches CSS generation problems early
- **Debug logging** with `DEBUG=astryx:*` reveals exactly which build script fails
- **Match CI behavior** by following the sequence in [`docs/release.md`](https://github.com/facebook/astryx/blob/main/docs/release.md)

## Frequently Asked Questions

### Why does Astryx fail to find workspace packages after a fresh clone?

The monorepo requires pnpm's workspace resolution to link internal dependencies. Run `pnpm install --frozen-lockfile` from the repository root, not `npm install` or `yarn`. The [`pnpm-workspace.yaml`](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml) file defines which directories contain packages, and pnpm creates symlinks between them during installation.

### How do I rebuild only the core package when debugging `@astryxdesign/core` imports?

Run `pnpm -C packages/core build` to build just the core package, then verify dependents compile with `pnpm -r exec -- tsc --noEmit`. The workspace build order in [`pnpm-workspace.yaml`](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml) ensures core builds before packages that depend on it, but manual intervention helps when iterating on core changes.

### What causes StyleX "unknown token" errors in production builds but not development?

Production builds run the full StyleX scanner via `scripts/verify-exports.mjs`, which validates all CSS variable references against [`packages/core/src/theme/vars.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/vars.stylex.ts). Development may skip this validation. Add missing variables to the theme file and re-run `pnpm stylex:scan` to regenerate the CSS definition map.