Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ import { Client } from 'ldapts'
✗ const { Client } = require('ldapts')
LDAPts is an ESM-first package, requiring `import` syntax.
Control
✓ import { Control } from 'ldapts/controls'
✗ const { Control } = require('ldapts/controls')
Generic LDAP controls are imported from a subpath. Specific control implementations are also available.
PagedResultsControl
✓ import { PagedResultsControl } from 'ldapts/controls'
✗ const { PagedResultsControl } = require('ldapts/controls')
Commonly used controls like PagedResultsControl are directly available from the controls subpath.
BerReader
✓ import { BerReader } from 'ldapts'
✗ const { BerReader } = require('ldapts')
BerReader and BerWriter are now exported directly from the main package entry point since v8.1.4, useful for custom BER parsing/writing.
InvalidAsn1Error
✓ import { InvalidAsn1Error } from 'ldapts'
✗ const { InvalidAsn1Error } = require('ldapts')
This error class is exported for explicit handling of malformed ASN.1 data, available since v8.1.4.
Demonstrates how to create an LDAPts client, bind to an LDAP server using credentials from environment variables, perform a basic search operation for entries, and then unbind gracefully. It includes basic error handling for common LDAP issues.
import { Client } from 'ldapts';
async function connectAndSearch() {
const ldapUrl = process.env.LDAP_URL ?? 'ldap://localhost:389';
const bindDN = process.env.LDAP_BIND_DN ?? 'cn=admin,dc=example,dc=com';
const bindPassword = process.env.LDAP_BIND_PASSWORD ?? 'password';
const searchBase = process.env.LDAP_SEARCH_BASE ?? 'dc=example,dc=com';
const searchFilter = process.env.LDAP_SEARCH_FILTER ?? '(objectClass=*)';
const client = new Client({
url: ldapUrl,
timeout: 5000, // Milliseconds client should let operations live for
connectTimeout: 5000, // Milliseconds client should wait for TCP connection
tlsOptions: {
minVersion: 'TLSv1.2', // Enforce minimum TLS version
rejectUnauthorized: false // Set to true in production with valid certs
},
strictDN: true
});
try {
console.log(`Attempting to bind as ${bindDN} to ${ldapUrl}...`);
await client.bind(bindDN, bindPassword);
console.log('LDAP bind successful!');
console.log(`Performing search under '${searchBase}' with filter '${searchFilter}'...`);
const { searchEntries, searchReferences } = await client.search(
searchBase,
{
filter: searchFilter,
scope: 'sub',
attributes: ['dn', 'cn', 'mail'], // Request specific attributes
sizeLimit: 10 // Limit results for example
}
);
if (searchEntries.length > 0) {
console.log(`Found ${searchEntries.length} entries.`);
searchEntries.forEach(entry => {
console.log(`- DN: ${entry.dn}, CN: ${entry.cn ?? 'N/A'}, Mail: ${entry.mail ?? 'N/A'}`);
});
} else {
console.log('No entries found.');
}
console.log('Unbinding from LDAP server...');
await client.unbind();
console.log('Unbind successful.');
} catch (error: any) {
console.error('LDAP operation failed:', error.message);
// Specific error handling for common LDAP issues
if (error.code === 'ETIMEDOUT') {
console.error('Timeout occurred. Check network connectivity or server responsiveness.');
} else if (error.code === 'LDAP_INVALID_CREDENTIALS') {
console.error('Invalid credentials provided for bind operation.');
} else if (error.message.includes('ECONNREFUSED')) {
console.error('Connection refused. Ensure the LDAP server is running and accessible.');
}
process.exit(1);
} finally {
if (client.connected) {
await client.unbind().catch(e => console.error('Error during final unbind:', e.message));
}
}
}
connectAndSearch();
Errors
Common errors & fixes
LDAP operation failed: LDAP_INVALID_CREDENTIALS
The Distinguished Name (DN) or password provided for the bind operation is incorrect.
fixVerify the `bindDN` and `bindPassword` are correct for the LDAP server. For Active Directory, the `bindDN` is often the User Principal Name (UPN) or `sAMAccountName` in a specific format.
LDAP operation failed: connect ECONNREFUSED
The client failed to establish a TCP connection to the LDAP server, often because the server is not running, is unreachable, or the port is blocked by a firewall.
fixEnsure the LDAP server is online and listening on the specified host and port. Check network connectivity between your application and the server, and verify any firewall rules.
LDAP operation failed: ETIMEDOUT
Either the TCP connection attempt or an LDAP operation timed out before a response was received.
fixIncrease `connectTimeout` for connection issues or `timeout` for operation issues in the `Client` constructor options. Also, check network latency or server load.
LDAP operation failed: InvalidAsn1Error: invalid BER: expected BER length to be less than or equal to the amount of data in the buffer.
The LDAP server responded with malformed BER-encoded data, indicating an issue with the server's response or a parsing error in the client.
fixThis often points to an issue with the LDAP server itself returning non-standard or corrupt data. Review the LDAP server logs for errors related to the request. Ensure `ldapts` is up to date, as parsing bugs are sometimes fixed in new versions.
Audit
Dependencies
No dependency data recorded yet.