Diagnostics

Every compile failure surfaces as a diagnostic: one message, owned by one source file, usually carrying a line and column. This page explains where those messages appear, how to read them, and then lists the ones a working project actually runs into, grouped by the stage that produced them.

Where diagnostics appear

The three bridge sinks are written together on every update, so they never disagree. The Output Log is a separate path and is the only surface that also shows success messages.

Diagnostics are owned by the source file that produced them. Recompiling A.dsm clears exactly the records A.dsm produced — including records attributed to an imported .dsh — without disturbing another material's diagnostics for the same header.

One severity

Severity defaults to "error" and is never assigned any other value anywhere in the plugin. Three consequences are worth knowing:

• Parse warnings — deprecated spellings, the missing-Outputs warning — never enter the store. They are appended to the compile result message and surface in the Output Log only.
• Log-only warnings likewise never enter the store.
• An extension that colours by severity paints every DreamShader entry as an error.

The Gen page tolerates a missing or non-error severity by filtering rather than failing, so a future severity level would not break it.

Reading a message

When a diagnostic carries a position it is formatted MSVC-style:

I:/Project/DShader/Materials/M_Sample.dsm(37,9): Unknown Graph identifier 'Tin'.

The {Placeholder} convention

Runtime substitutions are written as {Placeholder} in every table below. A brace run followed by ... — as in Graph = { ... } — is literal message text, not a placeholder.

Messages are quoted verbatim below, inconsistent punctuation included. One message really does end without a full stop, and it is marked where it appears.

Parse

Lexical scanning, top-level block headers, and the import inliner. These run before any section body is examined; a failure here aborts the whole file.

Sections and declarations

Section dispatch, the Outputs grammar, Layout, #Region, Group(…) scopes, and the post-parse validation of output declarations and bindings.

Graph statements and expressions

The statement and expression language inside Graph = { … }, plus constructors, swizzles and coercion. Parse-stage messages here are usually wrapped in the statement-level prefix In Graph statement '{Statement}': {Detail}.

Builtins

The UE.* and Substrate.* call surfaces in Graph, the UE.* declaration form in Properties, the math builtins, and the shared reflected-value writer. {Namespace} is UE or Substrate.

Functions and calls

Calling Function, GraphFunction, ShaderFunction, ShaderLayer, ShaderLayerBlend and VirtualFunction from Graph, and the generated HLSL helper include. {Kind} is the call kind.

Properties and parameters

Properties declarations, the [ … ] metadata block, parameter-node construction, Path( … ) asset references, and parameter reads from Graph.

Settings

The Settings section of a Shader — the special keys plus the reflected UMaterial property path — and the four keys a material-function Settings honours. {Key} echoes the lower-cased stored key, not the spelling that was typed.

Asset generation and saving

Pipeline gates, asset naming and root resolution, node-graph population, the ownership guard, and package saving.

Commandlet

-run=DreamShader and the cook-time generation hook. None of these reach the diagnostics store — the bridge does not run in a commandlet process.

VirtualFunction sync

The startup service that re-reads every VirtualFunction declaration and refreshes it from its UMaterialFunction asset. These reach the store with stage = virtualFunctionSync.

Warnings

Warnings never fail a compile and never enter the diagnostics store. They are appended to the compile result message, or logged under LogDreamShader.

Other warnings worth recognizing:

When nothing is reported

Some mistakes produce no message at all. The largest class by far is expression truncation: the Graph tokenizer turns every character it does not know — %, &, |, ^, <, >, ?, [, ! and the rest — into an end-of-expression token, and the parser accepts the expression that precedes it. a % b compiles as a, and if (x > 0 && y > 0) compiles as if (x > 0).

What Graph Is Not covers that page-length. A shorter list of the other silent cases lives on Limitations.

Success messages

The same pipeline returns these on success — useful when scripting a compile and matching on output.

One error, four surfaces

// DShader/Materials/M_Sample.dsm
Shader(Name="Materials/M_Sample")
{
    Properties = { vec3 Tint = vec3(1.0, 0.4, 0.1); }
    Outputs    = { vec3 Color; Base.EmissiveColor = Color; }
    Graph      = {
        vec2 UV = UE.TexCoord(Index = 0);
        Color   = Tin * UV.x;          // typo: Tin, not Tint
    }
}

Output Log:

LogDreamShader: Error: I:/Project/DShader/Materials/M_Sample.dsm(8,19): Unknown Graph identifier 'Tin'.

Saved/DreamShader/Bridge/diagnostics.json:

{
  "version": 1,
  "updatedAtUtc": "2026-07-29T11:04:22Z",
  "files": [
    {
      "path": "I:/Project/DShader/Materials/M_Sample.dsm",
      "diagnostics": [
        {
          "message": "Unknown Graph identifier 'Tin'.",
          "detail": "I:/Project/DShader/Materials/M_Sample.dsm(8,19): Unknown Graph identifier 'Tin'.",
          "stage": "generate",
          "code": "generate-error",
          "line": 8,
          "column": 19,
          "severity": "error",
          "source": "DreamShader Generate"
        }
      ]
    }
  ]
}

The same record goes to Bridge/diagnostics/<md5>.json and to the diagnostics table of Bridge/bridge.db, and shows up in the Dream Shader Gen page's source list — which is what the VSCode and Rider extensions read to draw the squiggle.

Fixing in order

When a file produces a wall of messages, work top-down. Later stages run on the output of earlier ones, so a single parse error can invent a dozen downstream complaints.

Where to next