Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
doh
✓ const doh = require('dns-over-http')
✗ import doh from 'dns-over-http'
CJS module; ESM import may not work without bundler or esm package.
doh
✓ const { default: doh } = await import('dns-over-http')
If using ESM, dynamic import with .default may be required.
doh.query
✓ const doh = require('dns-over-http'); doh.query({url}, questions, callback)
✗ doh.query('/dns-query', questions, callback)
First argument is an options object (including url), not a path string.
doh(opts)
✓ const handler = doh({ servers: ['1.1.1.1'] })
✗ const handler = doh.createServer({ servers: ['1.1.1.1'] })
doh() returns a request handler directly; no createServer method.
Creates a DoH server with HTTPS and performs two DNS queries via client.
const https = require('https');
const doh = require('dns-over-http');
const server = https.createServer({
cert: process.env.SSL_CERT || '',
key: process.env.SSL_KEY || ''
}, doh({
servers: ['9.9.9.9', '8.8.8.8', '1.1.1.1'],
maxAge: 600000
}));
server.listen(3000, () => {
console.log('DoH server listening on port 3000');
});
// Client example
const results = [];
const lookups = [
{ type: 'A', name: 'google.com' },
{ type: 'AAAA', name: 'google.com' }
];
for (const lookup of lookups) {
doh.query({
url: 'https://dns.google.com:443/experimental'
}, [lookup], (err, res) => {
if (err) throw err;
results.push(res.answers);
if (results.length === lookups.length) {
console.log(JSON.stringify(results, null, 2));
}
});
}
Errors
Common errors & fixes
TypeError: doh is not a function
ESM import of CJS module without default handling.
fixUse const doh = require('dns-over-http') or const { default: doh } = await import('dns-over-http'). Error: getaddrinfo ENOTFOUND
Missing or invalid DNS server address in options.servers.
fixProvide valid IP addresses like '8.8.8.8' in servers array.
TypeError: Cannot read properties of undefined (reading 'answers')
Response callback may receive null or undefined for failed queries.
fixCheck err first; if no error, ensure res has answers property: if (res && res.answers).
Audit
Dependencies
dns-packetrequiredUsed for encoding and decoding DNS wire format packets.