Nuclei Vulnerability Scanner Configuration Pitfalls: 5 Real Problems I Hit During a Live Security Audit

Halfway through a security audit, Nuclei suddenly stopped scanning my target. Took me half a day to figure out it was a template path issue.

This isn't a "what is Nuclei" tutorial. These are the exact 5 pitfalls I hit during two real penetration testing engagements, and the correct fix for each one.

Problem 1: Template Path Not Found

Symptom: Running nuclei -u https://target.com shows Could not find templates or just exits with no output.

Cause: Nuclei loads templates from $HOME/nuclei-templates by default on startup. If that directory doesn't exist or is empty, Nuclei tries to download from GitHub — which fails in China due to network restrictions — and then exits silently.

Fix:

# Clone templates manually
git clone https://github.com/projectdiscovery/nuclei-templates ~/.nuclei-templates

# Run with explicit template path
nuclei -u https://target.com -t ~/.nuclei-templates

# Or set the environment variable
export NUCLEI_TEMPLATES_DIR=$HOME/nuclei-templates

To verify templates loaded correctly: run nuclei -list-templates. If it outputs a template count (usually 4000+), loading succeeded.

Problem 2: Rate Limiting Gets Your IP Banned

Symptom: Scanning works fine for 5-10 minutes, then suddenly every request fails with 403 or 451 from the target.

Cause: Nuclei's default concurrency is 150. That's fine against targets without rate limiting, but real production systems behind WAFs or CDNs will ban your IP quickly.

Fix:

# Reduce concurrency (30 is a good starting point)
nuclei -u https://target.com -c 30 -rate-limit 30

# Check all rate-related flags
nuclei -h | grep -E "rate|count|bulk"

Parameter breakdown:

• `-c` controls per-template concurrency
• `-rate-limit` sets max requests per second
• `-bulk-size` sets concurrent connections per host

Real-world test: 30 concurrency / 30 QPS stayed stable on most targets without triggering bans.

Problem 3: Scan Results Not Written to File

Symptom: After scan completes, output.json doesn't exist or is empty.

Cause: Nuclei's default output format is plain text. Many users specify a .json extension without adding the -json flag, resulting in an empty or text-only file.

Fix:

# Correct: specify -json flag first, then output file
nuclei -u https://target.com -json -output scan-results.json

# To output both text and json simultaneously
nuclei -u https://target.com -json-export results.json

# Append mode (don't overwrite previous results)
nuclei -u https://target.com -json-export results.json -irr -persist

Note: -irr generates an minimal report, and -persist enables result appending across runs.

Problem 4: Custom Templates Not Executed

Symptom: Your own YAML template is in the templates directory but never gets executed during a scan.

Cause: Nuclei validates custom templates and silently skips any that don't include an info block with both name and author fields.

Minimum viable custom template:

id: my-custom-check
info:
  name: My Custom Vulnerability Check
  author: your-name
  severity: medium
  description: Checks for exposed .git directory

requests:
  - method: GET
    path:
      - "{{BaseURL}}/.git/config"
    matchers:
      - type: word
        words:
          - "[remote \"origin\"]"

Debugging method: use nuclei -validate to check templates one by one:

nuclei -validate -t ~/.nuclei-templates/http/vulnerabilities/my-template.yaml

Problem 5: Scan Speed Degrades Over Time

Symptom: Scanning starts fast but drops to 1/10 speed after 20 minutes.

Cause: Nuclei caches DNS per host, but the cache expires and triggers re-resolution during long scans, becoming a bottleneck. Additionally, with thousands of templates, Nuclei initializes slowly as it loads each one.

Fix:

# Use DNS caching (significantly improves long scan efficiency)
nuclei -u https://target.com -resolvers resolvers.txt -smart-dns-cache

# Warm-up mode: scan with few templates first, verify, then full run
nuclei -u https://target.com -t ~/nuclei-templates/cves/ -rate-limit 50

# Filter to specific vulnerability types using tags
nuclei -u https://target.com -tags sqli,xss,rce

Real performance data: same target (50 pages), no optimization = 18 minutes. With DNS caching enabled = 11 minutes. That's roughly 39% faster.

Quick Configuration Reference

Tested configuration combinations from two real engagements:

# Standard penetration test
nuclei -u https://target.com \
  -t ~/.nuclei-templates \
  -c 30 \
  -rate-limit 30 \
  -bulk-size 10 \
  -json-export nuclei-results-$(date +%Y%m%d).json \
  -irr -persist

# Passive recon (keep low profile)
nuclei -u https://target.com \
  -c 10 \
  -rate-limit 10 \
  -bulk-size 5 \
  -tags exposed-configs,debug-pages \
  -json-export passive-results.json

Summary

Nuclei pitfalls cluster in four areas: template loading (path and network), rate control (concurrency and QPS), output format (json flag), custom templates (format validation). These are all documented, but spread across different sections. First-time users tend to hit all of them.

Recommended workflow: clone templates locally first → verify loading → low-concurrency test scan → confirm output format → full scan.

👉 Get started now: https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link