Error Handling

Two Build Methods

build() — Never Throws

Returns a BuildResult, collects errors, and continues. Use when you want to handle failures gracefully (e.g. in a dev server or build pipeline that reports multiple issues).

buildOrThrow() — Fail-Fast

Throws on the first error. Use when a single failure should stop the build (e.g. CI/CD or production builds).

BuildResult Shape

type BuildResult = {
  success: boolean
  outputs: { name: string; path?: string; content: string }[]
  errors?: BuildError[]
}

• success — true if no errors occurred
• outputs — Array of generated outputs with name, path, and content
• errors — Present when success is false; array of BuildError

BuildError Shape

type BuildError = {
  message: string
  code: ErrorCode
  path?: string
  tokenPath?: string
  severity: 'error' | 'warning'
  suggestions?: string[]
}

• message — Human-readable error description
• code — Error code for programmatic handling
• path — File or token set path when relevant
• tokenPath — Dot-path to the token (e.g. color.action.brand)
• severity — error or warning
• suggestions — Optional hints (e.g. similar token names for typos)

Error Codes

Code	Description
TOKEN_REFERENCE	Unresolved alias {token.name}
CIRCULAR_REFERENCE	Circular alias chain
VALIDATION	Schema or structural validation failure
FILE_OPERATION	File read/write failure
CONFIGURATION	Invalid config
BASE_PERMUTATION	Missing base permutation for bundle mode
MODIFIER	Invalid modifier input or context
UNKNOWN	Unexpected error

Suggestions

TOKEN_REFERENCE errors often include suggestions with similar token names, helping you fix typos or wrong references.

Validation

Dispersa validates tokens and resolver documents against the official DTCG 2025.10 JSON schemas. Validation runs automatically during the Resolve and Parse pipeline stages and is configurable via validation.mode ('error' | 'warn' | 'off').

Validation What gets validated, when it runs, validation modes, and example errors.

Checking for Errors

import { build, buildOrThrow } from 'dispersa'

const result = await build({ resolver: './tokens.resolver.json', outputs: [...] })
if (!result.success) {
  for (const error of result.errors ?? []) {
    console.error(`[${error.code}] ${error.message}`)
    if (error.suggestions?.length) {
      console.log('  Did you mean:', error.suggestions.join(', '))
    }
  }
}

Error Classes (for buildOrThrow)

When using buildOrThrow(), Dispersa throws typed error classes from dispersa/errors. You can catch specific error types for programmatic handling:

import { TokenReferenceError, CircularReferenceError } from 'dispersa/errors'

try {
  await buildOrThrow({ resolver: './tokens.resolver.json', outputs: [...] })
} catch (error) {
  if (error instanceof TokenReferenceError) {
    console.log('Missing token:', error.referenceName)
    console.log('Suggestions:', error.suggestions)
  } else if (error instanceof CircularReferenceError) {
    console.log('Circular chain:', error.referencePath)
  }
}

Available error classes: DispersaError (base), TokenReferenceError, CircularReferenceError, ValidationError, FileOperationError, ConfigurationError, BasePermutationError, ModifierError.

Subpath Exports All available imports including dispersa/errors.

Output Formats — CSS Generate CSS custom properties from your tokens.