Error Messages

Common TDL errors and how to fix them.

Syntax Errors

Unknown Node Reference

Error: Unknown node "xyz" in edge definition

Cause: An edge references a node that wasn't defined.

Example:

[nodes]
  api:API

[edges]
  api->database  # Error: "database" not defined

Fix:

[nodes]
  api:API
  database:Database|cyl  # Add this

[edges]
  api->database

Missing Section

Error: Expected [nodes] section

Cause: Nodes defined without a section header.

Example:

@arch
api:API        # Error: no section
db:Database

Fix:

@arch
[nodes]        # Add this
  api:API
  db:Database

Invalid Diagram Type

Error: Unknown diagram type "@diagram"

Cause: Unrecognized diagram type declaration.

Example:

@diagram       # Error: not a valid type

Fix:

@arch    # or @seq, @flow, @state, @er

Indentation Error

Error: Unexpected indentation

Cause: Inconsistent or incorrect indentation.

Example:

[nodes]
api:API          # No indent
  db:Database    # Indented - inconsistent!

Fix:

[nodes]
  api:API        # All indented the same
  db:Database

Invalid Property

Error: Unknown property "invalid"

Cause: Using a property that doesn't exist.

Example:

[nodes]
  api:API|invalid:value  # Error

Fix:

[nodes]
  api:API|color:blue|shape:rect  # Valid

---

Unclosed Group

Error: Unclosed group "[GroupName"

Cause: Missing closing bracket or malformed group.

Example:

[nodes]
  [Backend     # Missing ]
    api:API

Fix:

[nodes]
  [Backend]    # Fixed
    api:API

Duplicate Node ID

Error: Duplicate node ID "api"

Cause: Two nodes have the same ID.

Example:

[nodes]
  api:API Gateway
  api:API Server   # Error: "api" already used

Fix:

[nodes]
  gateway:API Gateway
  server:API Server

Extension Warnings

Undeclared Extension (W103)

Warning W103: Using ext:icons without declaration

Cause: Using an extension feature without declaring it.

Example:

@arch
[nodes]
  lambda:Handler|icon:aws-lambda  # Warning: icons not declared

Fix:

@arch
#!ext icons                        # Add this

[nodes]
  lambda:Handler|icon:aws-lambda

Unknown Icon (W104)

Warning W104: Unknown icon "aws-unknown"

Cause: Referencing an icon that doesn't exist.

Fix: Check the Icon Library for valid icon names.

---

Edge Errors

Self-Reference in Edge

Error: Self-reference edge not allowed

Cause: An edge points to itself with solid arrow.

Example:

[edges]
  api->api  # Error in some contexts

---

Invalid Edge Operator

Error: Invalid edge operator "=>"

Cause: Using an operator that TDL doesn't support.

Example:

[edges]
  api=>db    # Error: => not valid

Fix:

[edges]
  api->db    # Solid arrow
  api-->db   # Dashed arrow
  api..db    # Dotted line
  api<->db   # Bidirectional

Style Errors

Unknown Style

Error: Unknown style "mystyle"

Cause: Referencing a style that wasn't defined.

Example:

[edges]
  api->db|style:mystyle  # Error: not defined

Fix:

[styles]
  mystyle: color:blue|width:2

[edges]
  api->db|style:mystyle

Debug Tips

1. Check indentation - TDL is whitespace-sensitive

2. Define nodes first - Before using in edges

3. Declare extensions - Before using extension features

4. Use unique IDs - No duplicate node identifiers

5. Valid operators - ->, -->, .., <->, <-->

Getting Help

If you encounter an error not listed here:

1. Check the Syntax Reference

2. Review the Specification

3. Open an issue on GitHub