• Overview - Back to API reference index
• Library Reference - Creating and managing .chalk libraries
• Compiler Reference - Using the .chalk compiler programmatically
• Custom Parsers - Creating custom parsers and parser priority
• Primitives Reference - Built-in data types and elements in .chalk
• Type Reference - Complete TypeScript type definitions

Troubleshooting

Table of Contents

• Common Errors
• Compilation Issues
• Library Issues
• Attribute Issues
• Getting Help

Common Errors

Element Not Found

Error: Element 'xyz' is not defined in the library

Cause: The element identifier doesn’t exist in your library.

Solutions:

• Check spelling of the element identifier
• Ensure the element is defined with lib.element() before compiling
• Verify the element is added to the library

// Add missing element
lib.element('xyz', {
  body: 'literal',
  attributes: {}
});

Attribute Type Mismatch

Error: Invalid number format or Boolean value must be true/false, yes/no, or 1/0

Cause: Attribute value doesn’t match the expected type.

Solutions:

• Check the attribute definition to see what type it expects
• Ensure your value matches the primitive type format
• For numbers, avoid non-numeric characters
• For booleans, use true/false, yes/no, or 1/0

// Wrong
element(count: abc; enabled: maybe)

// Correct
element(count: 42; enabled: true)

Required Attribute Missing

Error: Required attribute 'xyz' is missing

Cause: An attribute marked with required: true wasn’t provided.

Solutions:

• Add the missing attribute to your element
• Make the attribute optional in the definition (omit required or set to false)
• Add a default value in the attribute definition

// Make optional with default
lib.element('article', {
  attributes: {
    title: { type: 'string', default: 'Untitled' }
  }
});

Undefined Constant

Error: Undefined constant: xyz

Cause: Referenced a constant that wasn’t defined.

Solutions:

• Define the constant with @const(key: value) before using it
• Pass the constant via inputConstants parameter
• Check spelling of constant key in {{key}}

// Define before use
@const(version: 1.0.0)

Version: {{version}}

Compilation Issues

File Not Found

Error: File not found: path/to/file.part.chalk

Cause: Include or main file path is incorrect.

Solutions:

• Verify the file path is correct relative to baseDir
• Check file extension (.chalk for main files, .part.chalk for includes)
• Ensure the file exists at the specified location

// Use correct baseDir
const result = chalk.compileFile(
  'main.chalk',
  '/absolute/path/to/docs',  // baseDir
  library
);

Circular Include

Error: Circular include detected

Cause: Include files reference each other in a loop.

Solutions:

• Restructure your includes to avoid circular dependencies
• Create a common include file for shared content
• Use constants instead of includes for simple repeated content

Invalid Syntax

Error: Unexpected token or parsing errors

Cause: Malformed .chalk syntax.

Solutions:

• Check element syntax: element{body}(attrs) not element(attrs){body}
• Ensure attributes are properly formatted: key: value
• Verify multi-line attributes use proper indentation
• Check style guide for syntax conventions

// Wrong
callout(type: warning){Content}

// Correct
callout{Content}(type: warning)

Library Issues

Element Already Exists

Error: Element 'xyz' already exists in library

Cause: Attempting to add an element with a duplicate identifier.

Solutions:

• Use a different identifier
• Remove the existing element first
• Check for identifier conflicts with aliases

Type Not Found

Error: Type 'xyz' is not defined

Cause: Attribute references a type that doesn’t exist.

Solutions:

• Define custom types with lib.type() before using them
• Use a primitive type (string, number, boolean, etc.)
• Check spelling of type identifier

// Define custom type first
lib.type('url', {
  parser: (input) => {
    // validation logic
    return { ok: true, data: input };
  }
});

// Then use in attribute
lib.element('link', {
  attributes: {
    href: { type: 'url', required: true }
  }
});

Document Definition Missing

Error: Document definition is required

Cause: No document definition set in library.

Solutions:

• Define document when creating library

const lib = chalk.library({
  document: {
    class: 'article',
    body: 'all',
    attributes: {
      title: { type: 'string', required: true }
    }
  }
});

Attribute Issues

Multi-Word Identifiers

Attribute and constant identifiers can contain spaces:

// Valid
element(published date: 2024-01-01)
@const(app name: My Application)

Boolean Shorthand

Boolean attributes can be written without a value to mean true:

// These are equivalent
element(enabled: true)
element(enabled)

Enum Validation

Error: Invalid enum value

Cause: Value not in the enum’s allowed values.

Solutions:

• Check the enum definition for valid values
• Ensure exact match (case-sensitive by default)
• Define the enum before using it

lib.createEnum({
  identifier: 'status',
  values: ['draft', 'published', 'archived']
});

// Use valid enum value
// element(status: published) ✓
// element(status: invalid) ✗

Default Values

Attributes can have default values that apply when not specified:

chalk.createAttribute('visible', 'boolean', false, true)

// Element without 'visible' will get visible: true

Getting Help

Check Documentation

• Language Documentation - Chalk syntax and structure
• Library API - Creating elements and types
• Compiler API - Compiling Chalk files
• Primitives Reference - Built-in types and elements

Debugging Tips

1. Enable verbose errors: Check the CompileResult.error object for detailed messages
2. Validate incrementally: Test library definitions before full compilation
3. Check file paths: Use absolute paths to avoid ambiguity
4. Inspect library: Log library.elements and library.types to verify definitions
5. Test constants: Compile a simple document with constants first

Example Debug Pattern

const result = chalk.compile(source, library);

if (!result.ok) {
  console.error('Compilation failed:');
  console.error('Error:', result.error);
  console.error('Library elements:', Object.keys(library.elements));
  console.error('Library types:', Object.keys(library.types));
}