# How Astryx Developers Handle Stable Error Codes: A Complete Guide to ERR_UNKNOWN_COMPONENT

> Learn how Astryx developers master ERR_UNKNOWN_COMPONENT. Discover their strategy for stable error code handling using machine-readable codes for robust API and CLI integration. Get the complete guide.

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

---

**Astryx developers handle stable error codes by inspecting the machine-readable `code` field (e.g., `ERR_UNKNOWN_COMPONENT`) rather than parsing human-readable error messages, ensuring consistent error handling across CLI JSON output and programmatic API exceptions.**

Astryx provides a robust, append-only error code system designed for production stability. The framework guarantees that error codes remain constant while their human-readable descriptions may evolve, creating a reliable contract for both CLI consumers and programmatic API users.

## The Error Code Contract

Astryx enforces a strict separation between stable machine identifiers and volatile human-readable text. According to the source code in [`packages/cli/src/types/error-codes.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/error-codes.d.ts), the `ErrorCode` type defines an append-only enumeration where codes like `ERR_UNKNOWN_COMPONENT` never change meaning or spelling.

### Core Type Definitions

The error handling system relies on three key type definition files:

- **[`packages/cli/src/types/error-codes.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/error-codes.d.ts)** – Defines the `ErrorCode` type containing all stable identifiers including `ERR_UNKNOWN_COMPONENT`
- **[`packages/cli/src/types/api.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/api.d.ts)** – Declares the `AstryxError` class that extends native `Error` with a `code: ErrorCode` property
- **[`packages/cli/src/types/base.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/base.d.ts)** – Exports utility type guards `isError` and `isErrorCode` for safe runtime validation

## Handling CLI JSON Output

When using the CLI with the `--json` flag, errors serialize into structures conforming to `CLIError` or `CLIUnsupportedError`, both exposing the stable `code` property. The `parseResponse` and `isError` utilities from [`packages/cli/src/types/base.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/base.d.ts) provide type-safe parsing.

```typescript
import { parseResponse, isError } from '@astryxdesign/cli/json';

// Execute CLI command with JSON output
const raw = await execAsync('npx astryx component Buttn --json');
const result = parseResponse(raw);

if (isError(result)) {
  // Branch on stable code, never the error string
  switch (result.code) {
    case 'ERR_UNKNOWN_COMPONENT':
      console.error('Component not found. Did you mean:', result.suggestions?.[0].name);
      break;
    case 'ERR_CORE_NOT_FOUND':
      console.error('Core package missing – run `astryx init`');
      break;
    default:
      console.error(result.error); // Fallback for unknown codes
  }
}

```

This pattern ensures your automation remains stable even when error message wording updates in future releases.

## Handling Programmatic API Errors

When importing `@astryxdesign/cli/api` directly, functions throw `AstryxError` instances defined in [`packages/cli/src/types/api.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/api.d.ts). These objects expose the same stable `code` property available in CLI JSON output.

```typescript
import { component, AstryxError } from '@astryxdesign/cli/api';

async function getComponent(name: string) {
  try {
    const res = await component(name);
    console.log('Found component:', res.data.name);
  } catch (e) {
    if (e instanceof AstryxError) {
      switch (e.code) {
        case 'ERR_UNKNOWN_COMPONENT':
          console.warn(`No component named "${name}". Suggestions:`, e.suggestions);
          break;
        case 'ERR_CORE_NOT_FOUND':
          console.error('XDS core not installed – run `astryx init`');
          break;
        default:
          console.error(e.message);
      }
    } else {
      // Re-throw non-Astryx errors
      throw e;
    }
  }
}

```

The `AstryxError` class guarantees that the `code` property contains a value from the `ErrorCode` union type, enabling exhaustive switch statements.

## CI and Automation Patterns

For shell scripts and CI pipelines, combine the exit-code contract with JSON parsing. The CLI exits with code `0` only when no error shape is emitted, making it safe for pipeline logic.

```bash
#!/usr/bin/env bash
set -euo pipefail

# Run component lookup; exit 0 if component exists

if npx astryx component Button --json >/dev/null; then
  echo "✅ Component exists"
else
  # Capture JSON error for detailed logging

  err=$(npx astryx component Button --json 2>&1)
  echo "❌ Error: $err"
  exit 1
fi

```

This approach leverages the stable exit-code contract while preserving access to machine-readable error details via JSON.

## Summary

- **Inspect `code`, not `error`**: The `code` field in `ErrorCode` type (defined in [`packages/cli/src/types/error-codes.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/error-codes.d.ts)) remains stable, while human-readable messages may change.
- **Use type guards**: Import `isError` and `parseResponse` from [`packages/cli/src/types/base.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/base.d.ts) to safely handle CLI JSON output.
- **Catch `AstryxError`**: When using the programmatic API, import `AstryxError` from [`packages/cli/src/types/api.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/api.d.ts) to access the stable `code` property.
- **Trust exit codes**: The CLI returns `0` for success and non-zero for failures, safe for CI pipelines when combined with `--json` output.

## Frequently Asked Questions

### What is the difference between the error message and error code in Astryx?

The `error` property contains human-readable text that may change between versions, while the `code` property contains a stable machine-readable identifier like `ERR_UNKNOWN_COMPONENT`. You should always branch logic on the `code` field, defined in [`packages/cli/src/types/error-codes.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/error-codes.d.ts).

### How do I parse Astryx CLI JSON output safely?

Import `parseResponse` and `isError` from `@astryxdesign/cli/json` (types declared in [`packages/cli/src/types/base.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/base.d.ts)). These utilities validate the JSON structure and narrow the TypeScript type to distinguish between success and error responses without manual property checking.

### Can I rely on Astryx error codes in production CI pipelines?

Yes. Astryx error codes follow an append-only contract—they never change meaning or spelling once published. This makes them safe for production logic, feature flags, and CI automation that must survive framework updates.

### Where are Astryx error codes defined in the source?

All stable error codes are defined in [`packages/cli/src/types/error-codes.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/error-codes.d.ts) as the `ErrorCode` type. The `AstryxError` class implementing these codes is located in [`packages/cli/src/types/api.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/api.d.ts), with runtime validation utilities in [`packages/cli/src/types/base.d.ts`](https://github.com/facebook/astryx/blob/main/packages/cli/src/types/base.d.ts).