Template validation

Template validation ensures your Nuclei templates follow correct syntax and include all required fields. Nuclei provides built-in validation tools to catch errors before runtime.

Why validate templates?

Validation catches common issues:

Syntax errors

YAML formatting issues, indentation problems, and invalid field types

Missing fields

Required metadata like id, name, and author

Invalid values

Incorrect severity levels, malformed regex patterns, or invalid protocol configurations

Structural issues

Conflicting protocol declarations or incorrect field combinations

Validation methods

Command-line validation

The primary way to validate templates is using the -validate flag:

nuclei -validate -t template.yaml

Single template
Directory
Multiple templates

Validate a specific template file:

nuclei -validate -t git-config-exposure.yaml

Successful output:

[INF] Templates validation completed.

Validate all templates in a directory:

nuclei -validate -t ./custom-templates/

Validate specific templates:

nuclei -validate -t template1.yaml,template2.yaml

Build-time validation

For development, use the Makefile target:

make template-validate

This builds the nuclei binary and validates templates as shown in CONTRIBUTING.md and CLAUDE.md.

Validation rules

Mandatory field validation

Templates must include specific required fields. The validation logic in pkg/templates/parser_validate.go:13-37 enforces:

Template ID

Must be present and match the pattern ^([a-zA-Z0-9]+[-_])*[a-zA-Z0-9]+$:

id: valid-template-id  # Good

Invalid IDs will cause validation to fail:

id: Invalid Template ID  # Bad - contains spaces
id: template.with.dots    # Bad - contains dots

Template name

The info.name field cannot be blank:

info:
  name: Descriptive Template Name

Author information

At least one author must be specified:

info:
  author: pdteam
  # or
  author:
    - author1
    - author2

Optional field warnings

Some fields trigger warnings when missing (from pkg/templates/parser_validate.go:49-65):

info:
  name: Template Name
  author: pdteam
  severity: medium  # Warning if missing (except for workflows)

Warnings don’t prevent template execution but indicate fields you should include for completeness.

YAML syntax validation

Nuclei supports both strict and non-strict YAML parsing:

Strict mode (default)
Non-strict mode

Strict mode rejects unknown fields and requires exact syntax:

// From pkg/templates/parser.go:172-174
if !p.NoStrictSyntax {
    err = yaml.UnmarshalStrict(data, template)
}

This catches typos and invalid fields:

http:
  - method: GET
    pth: "{{BaseURL}}"  # Error: unknown field 'pth'

Disable strict syntax checking for legacy templates:

nuclei -no-strict-syntax -t template.yaml

Non-strict mode may hide configuration errors. Use only for legacy templates.

Validation errors

Common error messages

mandatory field is missing

Error message:

mandatory 'name' field is missing
mandatory 'author' field is missing
mandatory 'id' field is missing

Cause: Required metadata fields are not present.Solution: Add the missing fields to the info section:

id: template-id

info:
  name: Template Name
  author: your-username

invalid field format for 'id'

Error message:

invalid field format for 'id' (allowed format is ^([a-zA-Z0-9]+[-_])*[a-zA-Z0-9]+$)

Cause: Template ID contains invalid characters or format.Solution: Use only lowercase letters, numbers, hyphens, and underscores:

id: valid-template-name
# Not: Invalid Template Name

failed to parse PEM block

Error message:

Could not load template: failed to parse template

Cause: YAML indentation errors or invalid structure.Solution: Check indentation (use 2 spaces, no tabs):

http:
  - method: GET  # 2 spaces
    path:        # 4 spaces
      - "{{BaseURL}}"  # 6 spaces

use http or requests, both are not supported

Error message:

use http or requests, both are not supported

Cause: Template uses both deprecated requests and new http fields.Solution: Use only http (from pkg/templates/templates.go:362-364):

http:  # Use this
  - method: GET

# Not both:
# requests:
# http:

unknown field

Error message:

yaml: unmarshal errors:
  line 10: field headers not found in type http.Request

Cause: Misspelled field name or incorrect indentation.Solution: Check field spelling and indentation:

http:
  - method: GET
    headers:  # Correct spelling and indentation
      User-Agent: "Scanner"

Debugging validation failures

When validation fails:

Check YAML syntax

Use a YAML validator to check basic syntax:

# Using Python
python -c 'import yaml; yaml.safe_load(open("template.yaml"))'

# Using yq
yq eval template.yaml

Verify indentation

Ensure consistent 2-space indentation throughout:

# Check for tabs
grep -P '\t' template.yaml

Compare with working examples

Reference templates from the integration tests:

# View example templates
ls integration_tests/protocols/http/*.yaml

Use debug output

Run with debug flag for detailed error information:

nuclei -validate -t template.yaml -debug

Parser configuration

The template parser can be configured programmatically (from pkg/templates/parser.go:21-54):

parser := templates.NewParser()
parser.ShouldValidate = true     // Enable validation
parser.NoStrictSyntax = false    // Use strict YAML parsing

// Validate template
template, err := parser.ParseTemplate(templatePath, catalog)
if err != nil {
    // Handle validation error
}

Validation statistics

Nuclei tracks validation statistics internally:

SyntaxErrorStats: Count of templates with syntax errors
SyntaxWarningStats: Count of templates with warnings

These are incremented during validation in pkg/templates/parser.go:107-120.

Template format support

Nuclei supports multiple template formats:

YAML (recommended)
JSON

Standard format with preprocessing support:

id: example-template

info:
  name: Example Template
  author: pdteam
  severity: info

http:
  - method: GET
    path:
      - "{{BaseURL}}"

Alternative format (less common):

{
  "id": "example-template",
  "info": {
    "name": "Example Template",
    "author": "pdteam",
    "severity": "info"
  },
  "http": [
    {
      "method": "GET",
      "path": ["{{BaseURL}}"]
    }
  ]
}

JSON format is detected automatically but YAML is preferred for readability.

Validation best practices

Pre-commit validation

Integrate validation into your development workflow:

# Create pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
nuclei -validate -t ./templates/
if [ $? -ne 0 ]; then
    echo "Template validation failed"
    exit 1
fi
EOF

chmod +x .git/hooks/pre-commit

CI/CD integration

Add validation to your CI pipeline:

.github/workflows/validate.yml

name: Validate Templates

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Nuclei
        run: |
          go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
      
      - name: Validate Templates
        run: |
          nuclei -validate -t ./templates/

Editor integration

Use editor plugins for real-time validation:

VS Code

Install YAML extension for syntax highlighting and validation

IntelliJ/PyCharm

Built-in YAML support with schema validation

Validation workflow

Recommended workflow for template development:

Write template

Create your template using proper syntax and structure

Validate syntax

Run validation to catch errors:

nuclei -validate -t template.yaml

Fix errors

Address any validation errors or warnings

Test functionality

Run against test targets:

nuclei -t template.yaml -u http://test-target

Re-validate

Final validation before committing:

nuclei -validate -t template.yaml

Template loading errors

Validation can catch issues during template loading:

// From pkg/templates/parser.go:85-126
func (p *Parser) LoadTemplate(templatePath string) (bool, error) {
    // Parsing
    template, err := p.ParseTemplate(templatePath, catalog)
    
    // Mandatory field validation
    validationError := validateTemplateMandatoryFields(template)
    if validationError != nil {
        return false, validationError
    }
    
    // Optional field warnings
    validationWarning := validateTemplateOptionalFields(template)
    
    return true, nil
}

Mandatory field validation failures prevent template execution, while optional field warnings allow execution with logged warnings.

Next steps

Template signing

Learn about signing templates for security

Best practices

Follow guidelines for high-quality templates

Contributing

Submit validated templates to the community

Template structure

Understand template components in detail

Getting Started with Templates

Protocol Types

Template Features

Template Best Practices

Template validation

Why validate templates?

Syntax errors

Missing fields

Invalid values

Structural issues

Validation methods

Command-line validation

Build-time validation

Validation rules

Mandatory field validation

Optional field warnings

YAML syntax validation

Validation errors

Common error messages

Debugging validation failures

Parser configuration

Validation statistics

Template format support

Validation best practices

Pre-commit validation

CI/CD integration

Editor integration

VS Code

IntelliJ/PyCharm

Validation workflow

Template loading errors

Next steps

Template signing

Best practices

Contributing

Template structure

Build docs developers (and LLMs) love

Getting Started with Templates

Protocol Types

Template Features

Template Best Practices

​Why validate templates?

Syntax errors

Missing fields

Invalid values

Structural issues

​Validation methods

​Command-line validation

​Build-time validation

​Validation rules

​Mandatory field validation

​Optional field warnings

​YAML syntax validation

​Validation errors

​Common error messages

​Debugging validation failures

​Parser configuration

​Validation statistics

​Template format support

​Validation best practices

​Pre-commit validation

​CI/CD integration

​Editor integration

VS Code

IntelliJ/PyCharm

​Validation workflow

​Template loading errors

​Next steps

Template signing

Best practices

Contributing

Template structure

Build docs developers (and LLMs) love

Why validate templates?

Validation methods

Command-line validation

Build-time validation

Validation rules

Mandatory field validation

Optional field warnings

YAML syntax validation

Validation errors

Common error messages

Debugging validation failures

Parser configuration

Validation statistics

Template format support

Validation best practices

Pre-commit validation

CI/CD integration

Editor integration

Validation workflow

Template loading errors

Next steps