Knox S3 Client

Common errors

• TypeError: knox.createClient is not a function

  cause Attempting to use ES module import syntax (`import { createClient } from 'knox'`) with an older CommonJS-only library.
  fix Change your import statement to `const knox = require('knox');` in a CommonJS context.

• Error: SignatureDoesNotMatch

  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.
  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.

• Request body too small

  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.
  fix Calculate `Content-Length` using `Buffer.byteLength(yourString)` for accurate byte sizing in the HTTP header.

• UnknownEndpoint: Inaccessible host: `bucket.s3.amazonaws.com`. This service may not be available in the `us-west-2` region.

  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.
  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.

• Request entity too large

  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.
  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.

Warnings

• breaking 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.
  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.
• deprecated 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.
  Fix: Rewrite S3 integration using the official AWS SDK for JavaScript. For example, use `@aws-sdk/client-s3` for S3 operations.
• gotcha 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.
  Fix: Always use `Buffer.byteLength(myString)` for the `Content-Length` header when uploading string data with `client.put()`.
• gotcha 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.
  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.
• security 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.
  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.
• gotcha 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.
  Fix: Pass the `{'x-amz-acl': 'public-read'}` header to `client.put()`, `client.putFile()`, or `client.putBuffer()` methods if public readability is desired.

Install

• npm install knox npm
• yarn add knox yarn
• pnpm add knox pnpm

Imports

• createClient
  wrong:

  import { createClient } from 'knox';

  correct:

  var knox = require('knox');
  var client = knox.createClient({...});

  Knox is a CommonJS module only. Attempting to use ES module syntax (import) will result in a runtime error.

Quickstart

Demonstrates how to initialize the Knox client and upload a local file to S3 using the `putFile` method, including setting ACLs.

const knox = require('knox');
const fs = require('fs');
const path = require('path');

// Ensure you set these environment variables or replace with actual credentials
const S3_KEY = process.env.AWS_ACCESS_KEY_ID ?? 'YOUR_AWS_ACCESS_KEY_ID';
const S3_SECRET = process.env.AWS_SECRET_ACCESS_KEY ?? 'YOUR_AWS_SECRET_ACCESS_KEY';
const S3_BUCKET = process.env.AWS_BUCKET_NAME ?? 'your-bucket-name';

if (!S3_KEY || !S3_SECRET || !S3_BUCKET) {
  console.error('AWS credentials and bucket name must be set via environment variables or directly.');
  process.exit(1);
}

const client = knox.createClient({
  key: S3_KEY,
  secret: S3_SECRET,
  bucket: S3_BUCKET,
  region: 'us-east-1' // Specify your S3 region
});

const testFilePath = path.join(__dirname, 'test.txt');
fs.writeFileSync(testFilePath, 'Hello, Knox! This is a test file.');

// Example: Upload a file using putFile
client.putFile(testFilePath, '/uploads/test.txt', { 'x-amz-acl': 'public-read' }, (err, res) => {
  if (err) {
    console.error('Error uploading file:', err);
    return;
  }
  if (res && res.statusCode === 200) {
    console.log(`File uploaded successfully to: ${res.req.url}`);
    // Always either do something with `res` or at least call `res.resume()`.
    res.resume();
  } else {
    console.log(`File upload failed with status code: ${res ? res.statusCode : 'N/A'}`);
    if (res) res.resume();
  }

  // Clean up the local test file
  fs.unlinkSync(testFilePath);
});