Diagnostics

DreamShader » Diagnostics

Where DreamShader's diagnostics appear, how to read one, and what became of the messages of the 1.x generator. Every diagnostic a compile raises has a stable DSHnnnn code (since 2.0.0); the codes are the contract, the wording is not. The catalogue is README.md — every code with its severity and message — and each code has a section on its page, DSH1xxx.md … DSH9xxx.md, with every message raised under it, the places that raise it, a cause and a fix.

[!NOTE] Through 1.9.x most messages had no code: the 1.x parser coded its own, the 1.x generator's ~560 raise sites reported bare text, and this page catalogued that text verbatim. The generator and the parser are gone, and none of those strings is raised any more. If you have one in an old log or a search result, 1.x messages and their codes maps the common ones.

Where diagnostics appear

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

Diagnostics are owned by the source and the run that produced them. There are three kinds of run: the compile of a source, the shader compile of one material it generated, and the startup VirtualFunction scan of a file.

Within one file the records run compile first, then shader compile, then the VirtualFunction scan, by source within each, so the first error of a file is its compile's. See Bridge.

[!NOTE] The bridge never runs inside a commandlet. -run=DreamShader, -run=Cook and any other commandlet process writes no diagnostics.json, no shards and no bridge.db rows; the messages exist only in the log (and in a -DiagnosticsOut file). The bridge is also suppressed by -NoDreamShaderEditorBridge. See Commandlet.

Severity

A compile files its own records with the severity each was raised at -- a failed compile all of them, a successful one its warnings and notes (since 2.1.0; before, every stored diagnostic was error and a successful compile's warnings reached the Output Log only). The records the compile does not explain -- generate-error, material-compile, virtual-function-sync -- are error. The field and its values are on Bridge.

Log-only warnings (UE_LOG(LogDreamShader, Warning, …)) that are not a compile's records never enter the store. A client tolerates a missing or unknown severity by treating it as an error.

Message locations

A diagnostic is printed MSVC-style, with its code:

I:/Project/DShader/Materials/M_Sample.dsm(8,19): DSH4200: 'Tin' is not declared in this scope.

(since 2.0.0) Each file is lexed and parsed on its own, so a position is never mapped back from an assembled text. Through 1.9.x a parse error carried a near index {Index} offset into the import-inlined text, a position inside a section body was wrong, and most statement-level messages had no position at all.

A stage reports all of its errors — the parser and the binder keep going after one — and a stage with errors stops the pipeline before the next stage: a file with a syntax error is not bound, a file that does not bind is not emitted.

Reading a code

The leading digit is the stage that raises it; the full allocation is on DreamShaderLang 2.0.

A legacy rule (DSH5275–DSH5292) is something 1.x did that a 1.x source still gets, said out loud: a name matched only by case (DSH5275, DSH5276), a GLSL spelling (DSH5277), a wider vector cut down where a narrower one goes (DSH5289), an assignment that declares its variable (DSH5292). It is a warning or a note on a .dsm / .dsf, never in a .dss, and dsc migrate writes each one out as explicit 2.0 text.

1.x messages and their codes

The common messages of the 1.x parser and generator, and what reports the same condition today. {…} stands for what the message filled in.

A message that is in no row: search README.md for a word of its condition, or compile the file and read the code it reports now.

What 1.x accepted in silence

Conditions the 1.x generator accepted without a word — and built something other than what the text says, or dropped what it said. Each is a diagnostic now (since 2.0.0).

What 1.x documented and a 1.x source still relies on — a name in another case, a GLSL spelling, a float4 written into a float3 place — keeps building, as a legacy rule that says so.

VirtualFunction sync

The startup service that re-reads every VirtualFunction declaration and refreshes it from its UMaterialFunction asset, plus the editor actions on the Material Function toolbar and context menu. These messages have no DSHnnnn code, except DSH9001 for a source that uses #if.

Sync diagnostics reach the store with stage = virtualFunctionSync, code = virtual-function-sync and source = DreamShader VirtualFunction. The editor-action messages are toast notifications and log lines; they are not stored.

[!NOTE] The sync service finds a declaration by the bare keyword VirtualFunction, case-sensitively, with identifier boundaries on both sides — the same spelling the legacy front end requires of a block word. A lower-case virtualfunction is invisible to both.

Other log lines

Lines that are not a compile's records and never enter the store.

The commandlet's own run lines, its usage banner and its exit codes are on Commandlet; the decompiler's on Decompiler.

Example

A typo inside a Graph block, as it reaches each surface.

// 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): DSH4200: 'Tin' is not declared in this scope.

Saved/DreamShader/Bridge/diagnostics.json:

{
  "version": 1,
  "updatedAtUtc": "2026-10-04T11:04:22Z",
  "files": [
    {
      "path": "I:/Project/DShader/Materials/M_Sample.dsm",
      "diagnostics": [
        {
          "message": "'Tin' is not declared in this scope.",
          "detail": "I:/Project/DShader/Materials/M_Sample.dsm(8,19): DSH4200: 'Tin' is not declared in this scope.",
          "stage": "bind",
          "code": "DSH4200",
          "line": 8,
          "column": 19,
          "severity": "error",
          "source": "DreamShader Lang2"
        }
      ]
    }
  ]
}

The same record is written to Bridge/diagnostics/<md5>.json and to the diagnostics table of Bridge/bridge.db, and appears on the source's row in the Material Content Browser. stage follows from the code's range: preprocess, parse, bind, ir, generate or tools.

See also

• README.md — every code, with its severity and message
• Bridge — the request files, the WebSocket protocol, and the diagnostic artifacts
• Material Content Browser — the tab that shows each source's records
• Commandlet — -run=DreamShader, -DiagnosticsOut, its switches and exit codes
• DreamShaderLang 2.0 — the code ranges in full
• dsc migrate — the legacy rules, written out as 2.0 text
• Source files — the file-kind rules several codes enforce
• import — how a header is read, and the codes of an import
• Testing — the corpus fixtures that pin many of these codes