troubleshoot-errors

name: troubleshoot-errors description: Use when resolving LikeC4 errors—element not found, unknown kinds, invalid relationships, type mismatches, syntax failures. Provides root causes and fixes.

Troubleshoot LikeC4 Errors

Goal

Diagnose the root cause, verify it quickly, then show the smallest correct fix.

Default response shape:

probable error category
root cause
verification step
minimal fix

Prefer one corrected snippet over a long essay.

When to Use

Errors appear in the VS Code Problems panel
LikeC4 reports unknown kinds, unknown relationships, or missing elements
Views render incorrectly or show unexpected elements
Syntax errors appear after editing model/view/deployment files

Triage order

identify whether the problem is taxonomy, FQN, syntax, view scope, or deployment inheritance
compare the failing construct against shared specs and the project summary
verify the smallest relevant file/line
apply the minimal correction instead of compensating elsewhere

Quick reference

Symptom	Root cause	Minimal fix
`Element not found`	short name instead of FQN	use full FQN such as `system.api`
`Unknown kind`	undeclared element kind	replace with exact shared kind from `spec-*.c4`
`Invalid relationship kind`	undeclared or wrong-scope relationship type	use model kinds (`calls`, `async`, `reads`, `writes`, `uses`) or proper deployment kinds
`Unknown relationship type: https` in `model {}`	deployment type used in logical model	use `-[calls]->` + `technology 'HTTPS'`
syntax error in relationship block	kind placed in properties block	move the kind into the arrow
dynamic view parent → child	containment shown as interaction	have the actor or peer call the component directly
unexpected elements in view	include pattern too broad	scope includes to the intended boundary
`instanceOf target not found`	wrong FQN or wrong target type	point `instanceOf` to a real model container FQN
duplicate app edges in deployment	logical traffic restated in deployment	remove duplicate deployment edges and rely on inherited model relationships

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:

inspect the exact failing line and file type (model, view, or deployment)
compare it to projects/shared/SPEC_CHEATSHEET.md and projects/shared/spec-*.c4
inspect nearby FQNs and hierarchy in the local model files
give the minimal corrected snippet now
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.