{"id":14661,"library":"koa","title":"Koa Web Framework","description":"Koa is an expressive HTTP middleware framework for Node.js, designed to build web applications and APIs. It emphasizes a small core, relying on its middleware stack for functionality, and does not bundle any middleware. The current stable version is 3.2.0, with active development across both v2 and v3 branches, indicating a continuous release cadence.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/koajs/koa","tags":["javascript","web","app","http","application","framework","middleware","rack"],"install":[{"cmd":"npm install koa","lang":"bash","label":"npm"},{"cmd":"yarn add koa","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While Koa is published as CommonJS and `require` still works, `import` is generally recommended for new projects targeting Node.js v18+.","wrong":"const Koa = require('koa');","symbol":"Koa","correct":"import Koa from 'koa';"}],"quickstart":{"code":"import Koa from 'koa';\n\nconst app = new Koa();\n\n// response\napp.use(ctx => {\n  ctx.body = 'Hello Koa';\n});\n\napp.listen(3000, () => {\n  console.log('Koa server listening on port 3000');\n});","lang":"javascript","description":"A basic Koa server that listens on port 3000 and responds with 'Hello Koa' to all requests."},"warnings":[{"fix":"Update old middleware to use `async (ctx, next) => { await next(); }` syntax, or return a Promise from `next()`.","message":"Koa v3 removed support for the deprecated v1.x middleware signature. Middleware functions must now be `async` functions or return `Promise`s.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Install necessary middleware packages (e.g., `koa-router`, `koa-body`) and register them using `app.use()`.","message":"Koa provides a minimal core and does not bundle any middleware. Essential functionalities like routing, body parsing, or sessions must be added via separate middleware packages.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your development and production environments are running Node.js v18.0.0 or a newer compatible version.","message":"Koa requires Node.js v18.0.0 or higher due to its reliance on ES2015 features and async/await support.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade to Koa v2.16.4+ or the latest v3.x version to ensure security patches are applied.","message":"Versions of Koa prior to v2.16.4 and specific earlier v3.x releases contained a Host Header Injection vulnerability via `ctx.hostname` (GHSA-7gcc-r8m5-44qm).","severity":"gotcha","affected_versions":"<2.16.4, <3.0.0 (and specific earlier v3 patches)"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Declare your middleware function as `async`, e.g., `app.use(async (ctx, next) => { await next(); });`.","cause":"Attempting to use `await` within a Koa middleware function that is not declared as `async`.","error":"SyntaxError: await is only valid in async functions and the top level bodies of modules"},{"fix":"Ensure `await next();` is called exactly once within each middleware. Review error handling logic or early exits that might bypass `await next()`.","cause":"A Koa middleware function is invoking `next()` multiple times, or not awaiting it correctly, leading to re-entrancy issues.","error":"Error: next() cannot be called more than once"},{"fix":"Install the necessary Koa-compatible middleware package (e.g., `koa-views` for template rendering) and register it with `app.use()`.","cause":"Attempting to use a feature like template rendering (e.g., `ctx.render`) without installing and registering the corresponding Koa middleware.","error":"TypeError: ctx.render is not a function"},{"fix":"Ensure that `ctx.set()` or `ctx.body = ...` operations occur before any part of the response has been flushed. This often happens if `await next()` is omitted or if asynchronous operations continue after the response is sent.","cause":"Attempting to modify HTTP headers or send response content after the response has already been partially or fully sent to the client.","error":"ERR_HTTP_HEADERS_SENT: Cannot set headers after they are sent to the client"}],"ecosystem":"npm"}