AAL troubleshooting

Diagnose common AAL syntax, hierarchy, relationship, semantic type, and view errors when building C4 architecture diagrams.

AAL C4 v0.2 — Level-Aware Semantics

Use C4 AI Instructions with an external AI assistant, then copy its generated AAL into a new C4 Architecture project. Inspect diagnostics and explicitly Save.

Independent project copies

Use Clone to cloud or Clone to local from a project card’s menu. The copy includes the last saved source and layout; future changes do not sync. Duplicate keeps the same location. Cloning is available only on the Projects page. At three cloud projects, delete one to make room; existing cloud projects can still be saved.

Common Errors

Duplicate ID

Example

container API "API"
container API "Second API"

Error: Duplicate identifier "API" has already been defined.

Fix: Use a unique identifier for each element.

Semantic Type Level Mismatch

Example

component DB "Database" database

Error: Semantic type "database" is not valid for Component "DB".

Fix: "database" is valid at: Container. Suggested Component semantics: repository, dataaccess, store.

Unsupported Semantic Type

Example

container Vectors "Knowledge" vector-db

Error: Unsupported semantic type: vector-db

Fix: Did you mean "vectorstore"? Check the semantic type registry for valid values.

Invalid Relationship Mode

Example

API -> Bus "Publishes" {
    mode async-event
}

Error: Invalid relationship mode: async-event

Fix: Supported values: synchronous, asynchronous, event, stream, batch, file, tool (AI tool-call), a2a (agent-to-agent), realtime (WebSocket/SSE/WebRTC).

Invalid Protocol

Example

API -> Core "Calls" {
    protocol "htps"
}

Error: Invalid protocol: htps

Fix: Protocol is a controlled vocabulary. Did you mean "https"? Supported values include: https, grpc, graphql, websocket, kafka, mcp.

Unknown Relationship Target

Example

App -> MissingAPI "Calls"

Error: Relationship references "MissingAPI", but no element with that ID exists.

Fix: Ensure both source and destination IDs exist before defining a relationship.

Invalid Hierarchy

Example

system Platform "Platform" {
    component Auth "Authentication"
}

Error: A Component cannot directly belong to a System. Components must belong to Containers.

Fix: Move the component inside a container.

Reserved Keyword as ID

Example

container system "System"

Error: "system" is a reserved keyword and cannot be used as an identifier.

Fix: Choose a different name that is not a reserved keyword.

Unsupported Color

Example

container API "API" api {
    color electricblue
}

Error: Unsupported color "electricblue".

Fix: Supported values: default, gray, blue, cyan, teal, green, lime, yellow, amber, orange, red, rose, pink, purple, violet, indigo.