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
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.

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" databaseError: 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-dbError: 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.