Troubleshoot Errors

Quick reference

Minimal fix templates

1. Unknown kind

• Root cause: the element kind is not declared in shared specs
• Verify: check projects/shared/spec-*.c4 or the project summary
• Fix: replace guessed kinds with exact shared ones

// ❌ Wrong
api = Container_API 'API'

// ✅ Correct
api = Container_Api 'API' {
  technology 'Node.js'
  description 'Exposes the platform API.'
}

2. Wrong FQN / element not found

• Root cause: nested element referenced by short name only
• Verify: inspect parent hierarchy or use search-element
• Fix: use the full FQN

// ❌ Wrong
instanceOf api

// ✅ Correct
instanceOf corePlatform.api

3. Deployment relationship kind used in model {}

• Root cause: protocol encoded as relationship type instead of technology
• Verify: confirm you are in the logical model, not deployment
• Fix: keep the model relationship kind and move the protocol to technology

// ❌ Wrong
webApp -[https]-> api 'Makes API requests'

// ✅ Correct
webApp -[calls]-> api 'Makes API requests' {
  technology 'HTTPS'
}

4. Relationship kind inside block

• Root cause: calls, reads, or similar placed in the property block
• Verify: inspect the exact arrow syntax
• Fix: move the kind into the arrow

// ❌ Wrong
api -> service {
  calls 'Fetch data'
}

// ✅ Correct
api -[calls]-> service 'Fetch data'

5. Dynamic view parent → child error

• Root cause: a container is shown calling its own component in a dynamic view
• Verify: check whether both endpoints are in a containment chain
• Fix: have the actor or an external peer target the child directly

// ❌ Wrong
user -> system.webApp
system.webApp -> system.webApp.authModule

// ✅ Correct
user -> system.webApp.authModule 'Starts login'
system.webApp.authModule -> directoryService 'Validates credentials'

6. Duplicate deployment edges

• Root cause: normal application traffic was redrawn between deployment instances
• Verify: check whether the corresponding model relationship already exists
• Fix: keep the relationship in model {} and let instanceOf propagate it

// ❌ Wrong
Prod.Web.webApp -[https]-> Prod.App.apiApp 'Browser traffic'

// ✅ Better
webApp -[calls]-> api 'Browser traffic' {
  technology 'HTTPS'
}

View/layout-specific fixes

Invalid rank same

Only rank siblings that share the same parent context.

// ❌ Wrong
rank same ldapServer, devforge.postgresDb

// ✅ Correct
rank same devforge.api, devforge.database

Too many rank hints

• Root cause: the view is over-constrained
• Fix: remove most rank hints, keep autoLayout, then add at most one obvious anchor if still needed

Over-broad include

// ❌ Wrong
include **

// ✅ Better
include corePlatform.*
include -> corePlatform.api
include corePlatform.api ->

If MCP is unavailable

Use an offline diagnosis path:

1. inspect the exact failing line and file type (model, view, or deployment)
2. compare it to projects/shared/SPEC_CHEATSHEET.md and projects/shared/spec-*.c4
3. inspect nearby FQNs and hierarchy in the local model files
4. give the minimal corrected snippet now
5. list the MCP checks to run later (read-project-summary, find-relationships, search-element)

Common mistakes

• ❌ fixing the symptom without identifying the category of error first
• ❌ guessing kinds instead of comparing against shared specs
• ❌ working around a bad model with broader view includes
• ❌ using deployment relationship kinds in model {}
• ❌ redrawing inherited app traffic in deployment

Output

Return a short diagnosis with the root cause, the verification step, and a corrected snippet ready to paste.