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

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, 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 – Defines the ErrorCode type containing all stable identifiers including ERR_UNKNOWN_COMPONENT
• 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 – 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 provide type-safe parsing.

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. These objects expose the same stable code property available in CLI JSON output.

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.

#!/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) remains stable, while human-readable messages may change.
• Use type guards: Import isError and parseResponse from 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 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.

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). 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 as the ErrorCode type. The AstryxError class implementing these codes is located in packages/cli/src/types/api.d.ts, with runtime validation utilities in packages/cli/src/types/base.d.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}