{"id":15670,"library":"knox","title":"Knox S3 Client","description":"Knox is an Amazon S3 client library for Node.js, last updated in 2015 with version 0.9.3. It provided a familiar, low-level HTTP-client-like API for S3 operations such as `get()`, `put()`, and streaming uploads/downloads. At the time, it offered convenience methods like `putFile()` and `putStream()` for common file operations. Designed for Node.js environments from version 0.8 upwards, it was a common choice for S3 integration before the widespread adoption of the official AWS SDK v2/v3. However, the project is no longer maintained, with its last commit over eight years ago, and it is now considered abandoned. Users are strongly advised to migrate to the official AWS SDK for JavaScript for any new or existing S3 interactions due to security and compatibility concerns with unmaintained software.","status":"abandoned","version":"0.9.2","language":"javascript","source_language":"en","source_url":"git://github.com/LearnBoost/knox","tags":["javascript","aws","amazon","s3"],"install":[{"cmd":"npm install knox","lang":"bash","label":"npm"},{"cmd":"yarn add knox","lang":"bash","label":"yarn"},{"cmd":"pnpm add knox","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Knox is a CommonJS module only. Attempting to use ES module syntax (import) will result in a runtime error.","wrong":"import { createClient } from 'knox';","symbol":"createClient","correct":"var knox = require('knox');\nvar client = knox.createClient({...});"}],"quickstart":{"code":"const knox = require('knox');\nconst fs = require('fs');\nconst path = require('path');\n\n// Ensure you set these environment variables or replace with actual credentials\nconst S3_KEY = process.env.AWS_ACCESS_KEY_ID ?? 'YOUR_AWS_ACCESS_KEY_ID';\nconst S3_SECRET = process.env.AWS_SECRET_ACCESS_KEY ?? 'YOUR_AWS_SECRET_ACCESS_KEY';\nconst S3_BUCKET = process.env.AWS_BUCKET_NAME ?? 'your-bucket-name';\n\nif (!S3_KEY || !S3_SECRET || !S3_BUCKET) {\n  console.error('AWS credentials and bucket name must be set via environment variables or directly.');\n  process.exit(1);\n}\n\nconst client = knox.createClient({\n  key: S3_KEY,\n  secret: S3_SECRET,\n  bucket: S3_BUCKET,\n  region: 'us-east-1' // Specify your S3 region\n});\n\nconst testFilePath = path.join(__dirname, 'test.txt');\nfs.writeFileSync(testFilePath, 'Hello, Knox! This is a test file.');\n\n// Example: Upload a file using putFile\nclient.putFile(testFilePath, '/uploads/test.txt', { 'x-amz-acl': 'public-read' }, (err, res) => {\n  if (err) {\n    console.error('Error uploading file:', err);\n    return;\n  }\n  if (res && res.statusCode === 200) {\n    console.log(`File uploaded successfully to: ${res.req.url}`);\n    // Always either do something with `res` or at least call `res.resume()`.\n    res.resume();\n  } else {\n    console.log(`File upload failed with status code: ${res ? res.statusCode : 'N/A'}`);\n    if (res) res.resume();\n  }\n\n  // Clean up the local test file\n  fs.unlinkSync(testFilePath);\n});","lang":"javascript","description":"Demonstrates how to initialize the Knox client and upload a local file to S3 using the `putFile` method, including setting ACLs."},"warnings":[{"fix":"Migrate to the official AWS SDK for JavaScript (v2 or v3). Consider using specific S3 client modules like `@aws-sdk/client-s3` for modern applications.","message":"The Knox library is abandoned and has not been updated since 2015. It is not compatible with modern AWS SDKs or potentially newer S3 API changes and authentication mechanisms. Using it in new projects or maintaining it in old ones is highly discouraged.","severity":"breaking","affected_versions":"<=0.9.3"},{"fix":"Rewrite S3 integration using the official AWS SDK for JavaScript. For example, use `@aws-sdk/client-s3` for S3 operations.","message":"The entire Knox library is considered deprecated due to its age and lack of maintenance. There will be no further updates, bug fixes, or security patches. Its functionalities are superseded by the official AWS SDK.","severity":"deprecated","affected_versions":">=0.0.0"},{"fix":"Always use `Buffer.byteLength(myString)` for the `Content-Length` header when uploading string data with `client.put()`.","message":"When using `client.put()` with string data, `Content-Length` must be set to `Buffer.byteLength(string)` rather than `string.length` to correctly account for multi-byte characters, or S3 may reject the request or truncate the content.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure that `res.on('data', ...)` is handled, `res.pipe(...)` is used, or at minimum `res.resume()` is called within the response handler callback to drain the stream.","message":"After making an HTTP request with Knox (e.g., `client.put()`, `client.get()`), the response stream (`res`) must be consumed or explicitly resumed (e.g., `res.resume()`) to prevent the request from hanging and resources from leaking.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Immediately replace Knox with the official and actively maintained AWS SDK for JavaScript. Perform a thorough security audit on any system currently using Knox.","message":"Knox is an unmaintained library last updated in 2015. It likely contains unpatched security vulnerabilities in its own codebase or its outdated dependencies. Using it can expose applications to significant security risks, including supply chain attacks or unauthorized access to S3 buckets.","severity":"security","affected_versions":"<=0.9.3"},{"fix":"Pass the `{'x-amz-acl': 'public-read'}` header to `client.put()`, `client.putFile()`, or `client.putBuffer()` methods if public readability is desired.","message":"By default, Knox sets the `x-amz-acl` header to `private`. If you intend for uploaded objects to be publicly accessible, you must explicitly set `'x-amz-acl': 'public-read'` in the headers for each upload operation.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change your import statement to `const knox = require('knox');` in a CommonJS context.","cause":"Attempting to use ES module import syntax (`import { createClient } from 'knox'`) with an older CommonJS-only library.","error":"TypeError: knox.createClient is not a function"},{"fix":"Double-check your `key` and `secret` values. If they are correct, this indicates an incompatibility with modern S3 authentication, reinforcing the need to migrate to the official AWS SDK.","cause":"Incorrect AWS credentials (key, secret) or an outdated signature algorithm being used by Knox that is no longer accepted by S3 for certain operations or regions. This is common with older S3 clients.","error":"Error: SignatureDoesNotMatch"},{"fix":"Calculate `Content-Length` using `Buffer.byteLength(yourString)` for accurate byte sizing in the HTTP header.","cause":"When uploading string data directly with `client.put()`, the `Content-Length` header was incorrectly set to `string.length` instead of `Buffer.byteLength(string)`, leading to a mismatch in the expected byte count.","error":"Request body too small"},{"fix":"Ensure the `region` option in `createClient` is correct. If using a custom S3-compatible service, also provide the `endpoint` option. If the issue persists, the client is likely too old for the S3 infrastructure.","cause":"Misconfigured S3 region or endpoint, or the older Knox client may not correctly resolve specific S3 regional endpoints, especially for newer regions or custom S3-compatible services.","error":"UnknownEndpoint: Inaccessible host: `bucket.s3.amazonaws.com`. This service may not be available in the `us-west-2` region."},{"fix":"For large files, utilize `client.putStream()` with proper `Content-Length` or consider using external libraries like `knox-mpu` (if absolutely necessary to stick with Knox) or, preferably, migrate to the AWS SDK which handles multipart uploads automatically.","cause":"Attempting to upload a very large file (>100MB) without using multipart upload capabilities. Older versions of Knox or simplified `put` methods might not automatically handle multipart uploads.","error":"Request entity too large"}],"ecosystem":"npm"}