- 7 minutes to read

C4 Diagrams Troubleshooting

C4 Diagrams is part of experimental builds. To access this capability, contact your sales representative.

This page covers common questions and issues encountered when working with C4 Diagrams in Nodinite. For detailed reference material, see the linked sub-pages.

Reference Pages

Frequently Asked Questions

The import wizard didn't automatically match my System — why?

The import wizard performs a two-pass search for each node in your Mermaid source:

  1. First pass: searches Services by name
  2. Second pass: searches Systems by name

If a match is not found automatically, it is likely because:

  • The display name in the Mermaid markup differs from the entity name in the Repository (e.g., "ERP" in the diagram vs "SAP S/4HANA" in the Repository)
  • The System or Service has C4Type = None or no C4ContainerType set
  • The entity does not yet exist in the Repository

Fix: In the wizard resolution table, use the search field to find the correct entity, or choose Create new System / Create new Service to add it during import. Entities with C4Type = None on Systems do not appear in suggestions — set C4Type first, then re-import.

A Container node matched as a Service but it should be a System

The wizard's auto-match uses name similarity and prioritises Services over Systems. If a node such as Container(portal, "Portal", ...) matches a Service named "Portal" but you actually want it to bind to the "Portal" System:

Fix: In the wizard resolution table, find that row and change the resolution from Use existing Service to Use existing System, then select the correct System from the search dropdown. The C4ElementKind on the node controls rendering shape independently of whether the entity is a Service or a System.

I enabled UseContracts, but import still shows System/Service-only matching

This is expected in the current iteration. Contract improvements are focused on grouped runtime inspection and designer/view behavior, not import matching.

Fix: Continue importing with System/Service matching. After import, use the designer resolver to replace a Service binding with a Contract where needed.

Why does Systems mode now place some traffic under a different System when UseContracts=true?

When grouped runtime inspection resolves a single Contract, Systems mode uses that contract owner for boundary placement. This reduces incorrect placement in Unknown System for deterministic contract-owned traffic.

My node doesn't show a drill-through badge when I expected one

Drill-through badges () are created automatically when two diagrams in the same Diagram Set share a bound repository entity. If a badge is missing:

  • Check that both diagrams belong to the same Diagram Set — drill-through does not work across sets
  • Check that the node in the source diagram is bound to a Repository entity — placeholder nodes (unresolved during import) do not participate in drill-through
  • Check that the target diagram is Active — Draft diagrams appear in the set but are not shown as the canonical drill-through destination until promoted

Fix: In the import wizard for the target diagram, ensure the relevant node is resolved to the same Repository entity (same type and ID) as the node in the source diagram.

How do I have two L2 Container diagrams in the same Diagram Set?

This is fully supported and is one of the key advantages of Diagram Sets. Each L2 Container diagram gets its own Scope System — the System it zooms into.

  1. In the Diagram Set, click Import Diagram and select L2 Container
  2. In the Scope System field, select the System this L2 diagram is for (e.g., "ERP")
  3. Import the Mermaid markup for ERP's internal structure
  4. Repeat for the second L2: select a different Scope System (e.g., "Portal")

Both L2 diagrams coexist in the set. The L1 Context diagram's nodes for ERP and Portal (if bound to those Repository entities) will each show a drill-through badge pointing to their respective L2 diagrams.

The Mermaid output shows Container(...) for all nodes — no ContainerDb or ContainerQueue

The Mermaid type (Container, ContainerDb, ContainerQueue) is determined by the Service's C4ContainerType property:

  • Database → ContainerDb(...)
  • MessageBus → ContainerQueue(...)
  • All others → Container(...)

Fix: Set C4ContainerType = Database or C4ContainerType = MessageBus on the relevant Services or re-import the diagram after updating these properties. See Repository Properties for C4 Diagramming.

The C4 Diagrams menu item is not visible in the Repository navigation

C4 Diagrams requires the Mapify module license. If the navigation item is absent, contact your Nodinite administrator to verify that the module is enabled.

See Nodinite Licensing for guidance.

The Mermaid View renders but all connectors are missing

Connectors are imported automatically from Rel(...) or BiRel(...) entries in the Mermaid source. If no connectors appear:

  • The source Mermaid markup contained no Rel(...) or BiRel(...) entries
  • Connectors that reference a boundary alias (rather than a concrete node alias) are skipped during import — a warning toast indicates the count of skipped connectors

Fix: Re-import the Mermaid source with correct Rel(...) entries referencing node aliases (not boundary aliases). Node aliases follow the pattern svc_{id}, sys_{id}, or node_{id}.

A Person actor appears grey instead of blue

Grey person actors represent external persons (Person_Ext in C4 notation). This is intentional C4 model colour coding. If the actor should be an internal person, check the C4Type property on the System.

Fix: Open Repository → Systems → edit the System → set C4Type = Person (internal, renders blue) instead of C4Type = PersonExt (external, renders grey).

How do I create a bidirectional relationship arrow?

Include BiRel(from, to, "Label", "Tech") in your Mermaid source when importing. The import wizard preserves BiRel(...) entries and emits them correctly on every subsequent Mermaid generation.

What happens to boundary types when I import a diagram?

The boundary type (Container_Boundary, System_Boundary, Enterprise_Boundary, Boundary, Deployment_Node) is auto-detected from the Mermaid macro in your source and stored per boundary element. No manual configuration is required. If the wrong type appears in the Mermaid output, re-import the diagram with the correct Mermaid macro in the source.

Can I nest one boundary inside another?

Yes. When your Mermaid source has a Boundary { } block nested inside another Boundary { } block, the import wizard stores the parent–child relationship. The Mermaid generator re-emits the correct nested boundary structure. Nesting is per-diagram and does not affect Domains in BPM or other diagrams.

Can I place a System (Person or External System) inside a boundary instead of at the top level?

Yes. When your Mermaid source has a System(...) or Person(...) element declared inside a Boundary { } block, the import wizard stores it as a member of that boundary. The Mermaid generator re-emits it inside the boundary block.

Does changing C4ContainerType on a Service affect my BPM diagrams?

No. C4ContainerType and C4Technology are used only by C4 Diagrams. BPM, Log Views, Monitor Views, and the Integration Landscape are not affected by these properties.

Can I have the same architectural subject in multiple layout variants (As-Is vs To-Be)?

Yes. Create two separate diagrams within the same Diagram Set — one named "As-Is" and one named "To-Be" (or "Current" and "Target"). Promote the canonical view to Active and keep the working version as Draft until it is ready.

Why do Component_Ext (or Container_Ext) nodes show as "External" in the import wizard with no matching option?

External element variants (Component_Ext, ComponentDb_Ext, ComponentQueue_Ext, Container_Ext, ContainerDb_Ext, ContainerQueue_Ext) represent third-party or out-of-scope building blocks whose definitions live outside your system boundary. During import, these nodes are automatically stored as unbound placeholders — the wizard does not search the Repository for a match, and no resolution is required from you.

In the Review and Resolve table, these rows display:

  • A grey External badge in the Status column
  • "Unbound placeholder" with a icon in the Action column

They are not counted as conflicts and do not block the Apply button. After the diagram is created, you can optionally bind an unbound placeholder to a Repository entity (Integration, Service, or System) using the C4 Designer.

The PNG export is blank or very small

Fix: Open the /mermaid URL for the diagram and verify the Mermaid markup is valid. Paste it into the Mermaid Live Editor to confirm it renders correctly.