All Products
Search

This Product

    Object Storage Service:Initialization code and common errors for uploading and downloading files in Node.js SDK

    Document Center

    Object Storage Service:Initialization code and common errors for uploading and downloading files in Node.js SDK

    Last Updated:Mar 20, 2026

    The ali-oss Node.js SDK uses a single client object for all upload and download operations. This page covers how to initialize that client and explains the two error types the SDK returns when an operation fails.

    Initialize the SDK

    Install the ali-oss package, then create a client with your bucket credentials:

    const OSS = require('ali-oss');

const client = OSS({
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,         // AccessKey ID
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET, // AccessKey secret
  bucket: 'your-bucket-name',
  region: 'oss-cn-hangzhou',  // The region where your bucket is located, in OSS region format
  // stsToken: process.env.OSS_STS_TOKEN,  // Include when using STS temporary credentials
  // secure: true,                         // Set to true to use HTTPS
});

    Parameter notes:

    ParameterRequiredDescription
    accessKeyIdYesYour AccessKey ID
    accessKeySecretYesYour AccessKey secret
    bucketYesThe name of your OSS bucket
    regionYesThe region where your bucket is located, in OSS format — for example, oss-cn-hangzhou. This is the bucket's region, not the region of the machine making the request.
    stsTokenConditionalRequired when using Security Token Service (STS) temporary credentials
    secureNoSet to true to use HTTPS
    Important

    Store credentials in environment variables, not in source code. Hardcoded credentials risk exposure if your code is committed to version control.

    Common errors

    The SDK returns two error types for upload and download operations.

    ClientError

    ClientError is an internal SDK error. It occurs when:

    • A parameter is set incorrectly

    • An object is modified during a resumable upload or resumable download

    Check your client configuration and parameter values if you see this error.

    ServerError

    ServerError is returned when the OSS server rejects a request. The SDK parses the server's error response and exposes the following attributes:

    AttributeTypeDescription
    statusnumberHTTP status code of the failed request, for example, 403, 404
    codestringOSS error code, for example, AccessDenied, NoSuchBucket
    messagestringHuman-readable description of the error
    requestIdstringUUID that uniquely identifies the request — include this in support requests

    Use status and code together to identify what went wrong.

    The following example shows how to catch and inspect a ServerError in practice:

    try {
  await client.put('example-object.txt', Buffer.from('hello'));
} catch (err) {
  if (err.name === 'ServerError') {
    console.error('Status:', err.status);       // HTTP status code
    console.error('Code:', err.code);           // OSS error code
    console.error('Message:', err.message);     // Error description
    console.error('Request ID:', err.requestId); // Unique request identifier
  }
}

    If you contact Alibaba Cloud support, always provide the requestId value — it lets support engineers locate the exact request in server logs.

    What's next