Debugging

Active contributors: ulisesgascon, jonchurch, wesleytodd

Express logs through the debug package. Most subsystems instantiate a namespaced logger and emit lifecycle events behind DEBUG=express:*.

Enabling debug output

DEBUG=express:* node app.js

To narrow scope:

DEBUG=express:application,express:view,express:router node app.js

Namespaces in this repository:

Namespace	Source	Logs
express:application	lib/application.js	"booting in %s mode", "set %s to %o", .use app under %s
express:view	lib/view.js	lookup, stat, render, require for engine modules
express:router	The external router package	Route stack execution, parameter handling

The body-parser, serve-static, send, and finalhandler packages each have their own debug namespaces (body-parser:json, send, finalhandler, etc.).

Common errors

"No default engine was specified and no extension was provided."

Thrown from the View constructor in lib/view.js. Either pass a filename with a known extension to res.render/app.render, or set app.set('view engine', 'ejs') (or your engine of choice).

'Failed to lookup view "..." in views directory "..."'

Generated in app.render (lib/application.js) when View.lookup returns no path. Check app.set('views', dir) and that the file exists with the expected extension.

'callback function required' from app.engine

app.engine(ext, fn) requires fn to be a function. Most template engines export __express or renderFile. See Features / Templating.

'app.use() requires a middleware function'

app.use flattens its arguments and rejects empty stacks. If you app.use(undefined) or pass a non-function, you get this message.

'Invalid status code: ... Status code must be greater than 99 and less than 1000.'

res.status is strict in Express 5+. Only integers in [100, 999] are allowed; out-of-range values throw RangeError, non-integers throw TypeError. This was a deliberate Express 5 breaking change (see Lore).

'cookieParser("secret") required for signed cookies'

res.cookie(name, value, { signed: true }) requires req.secret to be set, which is what cookie-parser does. Mount cookie-parser before any signed-cookie writer.

'path must be absolute or specify root to res.sendFile'

res.sendFile (in lib/response.js) throws when given a relative path without options.root. Pass an absolute path or { root: __dirname }.

Common gotchas

• Mounted apps inherit settings via prototype, so changes to a parent app's settings are visible in mounted sub-apps unless the sub-app overrode them. This is intentional but surprises people. See app.defaultConfiguration / the 'mount' event handler in lib/application.js.
• req.ip requires trust proxy to be configured if you sit behind a load balancer; otherwise it returns the proxy's address. Use app.set('trust proxy', 'loopback') or pass an array of CIDRs.
• res.send(object) calls res.json(object) internally, but res.send(string) defaults to text/html. To send plain text, set res.type('txt') first.
• res.redirect(undefined) is deprecated in Express 5 (logs a warning via the depd-style deprecate helper). Always pass a string URL.
• Streaming bodies bypass etag fn. ETag is only computed for in-memory Buffer/string bodies in res.send.

Profiling and performance

Express does not ship its own profiler. For perf debugging:

• Use Node's built-in --prof and --cpu-prof flags.
• Use process.hrtime for ad-hoc timing inside middleware.
• The Coveralls coverage report at coveralls.io/r/expressjs/express shows which branches are exercised; uncovered code is often less optimised than covered code.

Related pages

• Systems / Application — covers settings, mounting, and app.handle.
• Patterns and conventions — for the debug namespace style.