AAL troubleshooting

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

Acefy Architecture Language (AAL) · AAL C4 0.2 · Level-aware semantics

On this page
Independent diagram copies
Copy to Cloud or Local creates an independent diagram in the chosen destination and leaves the original open. Future changes do not sync. Duplicate keeps the same project and location. Cloud folder and diagram counts are unlimited; document size and write-rate limits still apply.
Projects panel with a folder expanded to show its diagrams and Markdown documents
Expand a folder to browse its diagrams and Markdown documents. Click an item to open it.

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, slate, silver, charcoal, stone, brown, chocolate, sand, peach, coral, burgundy, salmon, mint, emerald, olive, sky, navy, lavender.