What causes "blockType must be defined" in BabylonJS/Babylon.js?

Add the blockType annotation to the fragment shader (the annotated-comment header ParseFragmentShader reads).

blockType must be defined

Error message

blockType must be defined

What it means

ImportAnnotatedGlsl parses an annotated GLSL fragment shader to derive a serialized shader block definition. The blockType is extracted from the shader's annotations; if parsing produces no blockType, the import aborts because every custom block must be registered under a unique block type. This is a validation of the shader source content itself.

Source

Thrown at packages/dev/smartFilters/src/serialization/importCustomBlockDefinition.ts:60

        }

        return blockDefinition;
    }
}

/**
 * Converts a fragment shader .glsl file to an SerializedBlockDefinition instance for use
 * as a CustomShaderBlock. The .glsl file must contain certain annotations to be imported.
 * See readme.md for more information.
 * @param fragmentShader - The contents of the .glsl fragment shader file
 * @returns The serialized block definition
 */
function ImportAnnotatedGlsl(fragmentShader: string): SerializedShaderBlockDefinition {
    setLogger(Logger);
    const fragmentShaderInfo = ParseFragmentShader(fragmentShader);

    if (!fragmentShaderInfo.blockType) {
        throw new Error("blockType must be defined");
    }

    // Calculate the input connection points
    const inputConnectionPoints: SerializedInputConnectionPointV1[] = [];
    for (const uniform of fragmentShaderInfo.uniforms) {
        // Add to input connection point list
        const inputConnectionPoint: SerializedInputConnectionPointV1 = {
            name: uniform.name,
            type: uniform.type,
            autoBind: uniform.properties?.autoBind as InputAutoBindV1,
        };
        if (inputConnectionPoint.type !== ConnectionPointType.Texture && uniform.properties?.default !== undefined) {
            inputConnectionPoint.defaultValue = uniform.properties.default;
        }
        inputConnectionPoints.push(inputConnectionPoint);
    }

    return {

View on GitHub (pinned to 0592b347b8)

Solutions

Add the blockType annotation to the fragment shader (the annotated-comment header ParseFragmentShader reads).
Check annotation spelling/format against the parser's expected syntax.
Confirm the annotation survives minification/formatters — keep it in a block comment the parser recognizes.
Ensure you are passing the fragment shader source, not a file path or a compiled program.
Re-export a working custom shader block from the editor to see a correct annotation example.

Example fix

// before
const glsl = `uniform float amount; void main() {}`; // no annotations
// after
const glsl = `//blocktype MyShaderBlock
uniform float amount; void main() {}`; // annotation present per parser format

Defensive patterns

Strategy: validation

Validate before calling

function validateShaderBlockType(fragmentShader) {
  // mimic the annotated-GLSL convention: blockType must appear in the shader header
  if (!/blockType\s*[:=]?\s*\S+/i.test(fragmentShader)) {
    throw new Error("Fragment shader is missing its blockType annotation");
  }
}

Type guard

function isAnnotatedShader(src) {
  return typeof src === "string" && /blocktype/i.test(src);
}

Try / catch

try {
  const def = ImportCustomBlockDefinition({ format: "glsl", fragmentShader });
} catch (e) {
  if (e.message === "blockType must be defined") {
    throw new Error("GLSL source lacks the blockType annotation — add the annotated header");
  }
  throw e;
}

Prevention

Keep the blockType annotation comment at the top of every custom shader.
Configure formatters/minifiers to preserve the annotation comments.
Copy shaders from the editor export to guarantee correct annotation syntax.
Pass raw shader source text, not paths or compiled output.
Lint custom shaders for required annotations before import.

When it happens

Trigger: Calling ImportCustomBlockDefinition (or ImportAnnotatedGlsl directly) with a fragment shader string that lacks the blockType annotation — e.g. the special comment/directive declaring the block type was removed, misspelled, or the shader was written as plain GLSL without any Smart Filter annotations.

Common situations: Migrating plain Babylon shader code into a Smart Filter custom block, editing shader files with formatters that strip special comments, copy-pasting shaders without their header annotations.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/c1d9691e7c44741a. Report an issue: GitHub.