JSforce Salesforce API Library

Common errors

• INVALID_LOGIN: Invalid username, password, security token; or user locked out.

  cause Incorrect Salesforce credentials (username, password, or security token) or the user's account is locked.
  fix Verify username and password. Append your security token directly to the password if it's required and you haven't whitelisted your IP. Check Salesforce setup for IP ranges and user lockout status. Ensure the correct login URL (e.g., `https://test.salesforce.com` for sandboxes) is used.

• sObject type 'NonExistentObject__c' is not supported.

  cause Attempting to query or interact with an sObject (standard or custom object) that does not exist or is misspelled in the Salesforce organization.
  fix Double-check the API name of the sObject. For custom objects, ensure the `__c` suffix is correct. Verify that the user has permissions to access the object.

• Syntax error. Extra ','

  cause An invalid SOQL query string was provided, often due to a misplaced comma, missing FROM clause, or incorrect field name.
  fix Carefully review the SOQL query string for syntax errors. Validate field names and object names against your Salesforce schema. Test the query directly in the Salesforce Developer Console to isolate issues.

Warnings

• breaking Major breaking changes exist between v1 and v3. Users migrating from older versions (especially v1) must consult the dedicated migration guide as API signatures and authentication mechanisms have significantly evolved.
  Fix: Refer to the official 'MIGRATING_V1-V3.md' guide in the jsforce GitHub repository for detailed steps and code changes required for migration.
• breaking Breaking changes were also introduced between v2 and v3. While less extensive than v1 to v3, developers upgrading from v2 should review the migration notes to ensure compatibility.
  Fix: Consult the 'MIGRATING_V2-V3.md' guide within the jsforce GitHub repository for specific changes and updates needed.
• deprecated The SOAP login() API (used by `loginBySoap` method) will be retired by Salesforce in Summer '27 (API version 65.0). Continued use after this date will result in authentication failures.
  Fix: Migrate authentication flows from `loginBySoap` to OAuth 2.0 Username-Password Flow or other OAuth 2.0 flows (e.g., Web Server Flow, JWT Bearer Flow) as appropriate for your application. Refer to Salesforce Release Notes for more information.
• gotcha The default `jsforce` export is typically the `Connection` class or an object that contains it, leading to common mistakes in named imports (e.g., `import { Connection } from 'jsforce'`).
  Fix: Always use a default import for the main library: `import jsforce from 'jsforce';` then access `jsforce.Connection` or `new jsforce.Connection(...)`. For CommonJS, use `const jsforce = require('jsforce');`.

Install

• npm install jsforce npm
• yarn add jsforce yarn
• pnpm add jsforce pnpm

Imports

• Connection
  wrong:

  import { Connection } from 'jsforce';

  correct:

  import jsforce from 'jsforce'; const conn = new jsforce.Connection({});

  The primary entry point, `jsforce.Connection`, is typically accessed via the default import (or `require`) of the library, as `jsforce` itself is the Connection class or an object containing it.
• OAuth2
  wrong:

  import { OAuth2 } from 'jsforce';

  correct:

  import jsforce from 'jsforce'; const oauth2 = new jsforce.OAuth2({});

  Similar to Connection, `OAuth2` is a property of the main `jsforce` export.
• Tooling
  wrong:

  import { Tooling } from 'jsforce';

  correct:

  import jsforce from 'jsforce'; const tooling = conn.tooling;

  Specific APIs like Tooling, Metadata, or Bulk are accessed as properties on an authenticated `jsforce.Connection` instance, not directly imported from the package.

Quickstart

This code snippet demonstrates how to establish a connection to Salesforce using jsforce, authenticate with username-password flow (suitable for scripts or backend services), perform a SOQL query to fetch account data, create a new Lead record, and then retrieve it. It highlights basic CRUD operations and error handling, showcasing the core interaction pattern with the Salesforce API.

import jsforce from 'jsforce';

async function connectAndQuery() {
  const conn = new jsforce.Connection({
    // When using OAuth2, configure it here. For username/password flow, loginUrl is sufficient.
    // oauth2: {
    //   loginUrl: process.env.SF_LOGIN_URL ?? 'https://login.salesforce.com',
    //   clientId: process.env.SF_CLIENT_ID ?? '',
    //   clientSecret: process.env.SF_CLIENT_SECRET ?? '',
    //   redirectUri: process.env.SF_REDIRECT_URI ?? '',
    // }
    loginUrl: process.env.SF_LOGIN_URL ?? 'https://login.salesforce.com'
  });

  try {
    // Authenticate using username-password flow (convenient for scripts, but consider OAuth for broader applications)
    await conn.login(
      process.env.SF_USERNAME ?? '',
      process.env.SF_PASSWORD_TOKEN ?? '' // password + security token (if enabled)
    );
    console.log('Successfully connected to Salesforce!');
    console.log('Instance URL:', conn.instanceUrl);
    console.log('User ID:', conn.userInfo?.id);

    // Perform a SOQL query to fetch the first 5 Account records
    const result = await conn.query<{ Id: string; Name: string }>('SELECT Id, Name FROM Account LIMIT 5');
    console.log('Query Results (first 5 Accounts):');
    result.records.forEach(record => {
      console.log(`  ID: ${record.Id}, Name: ${record.Name}`);
    });

    // Example: Create a new Lead record
    const createResult = await conn.sobject('Lead').create({
      LastName: `JSforce Lead ${Date.now()}`,
      Company: 'JSforce Corp',
      Status: 'Open - Not Contacted'
    });
    console.log(`Created Lead with ID: ${createResult.id}, success: ${createResult.success}`);

    // Example: Retrieve the newly created Lead record
    if (createResult.success) {
      const retrievedLead = await conn.sobject('Lead').retrieve(createResult.id);
      console.log(`Retrieved Lead: ${retrievedLead.LastName} from ${retrievedLead.Company}`);
    }

  } catch (err: any) {
    console.error('Error connecting or performing Salesforce operations:', err.message);
  }
}

connectAndQuery();