Troubleshooting | Docusign

This page describes the causes of and resolutions for common Docusign CLI errors.

Installation, authentication, and permission errors

EPERM: operation not permitted error when running scaffold command

Description
When you attempt to set up a workspace with the scaffold command, the CLI returns this error:

Error creating scaffold: EPERM: operation not permitted, mkdir \[directory path\]

Cause
The CLI does not have permission to write to the directory specified in the scaffold command, or to the current directory if the command did not specify a directory.

Recommendations
Do either of the following to create the workspace in a directory that the CLI can write to:

If you ran the command without specifying a directory, change to a directory that the CLI can write to, and run the command again.
Include a directory path in the \-w option. For example:
ds scaffold \-w ..\\..\\workspaces\\my\_new\_workspace \-p my\_new\_project

npm error EACCESS: permission denied

Description
When attempting to install the Docusign CLI for the first time, even if you have admin permissions and use the sudo version of the command, you receive this error:

npm error Error: EACCES: permission denied, mkdir '/usr/local/lib/node\_modules/@docusign'

Cause
npm cannot write to the specified directory, even with admin privileges.

Recommendation
Configure npm to install global packages under your user account. Below is an example bash script:

mkdir \-p "\$HOME/.npm-global"
npm config set prefix "\$HOME/.npm-global"
echo 'export PATH="\$HOME/.npm-global/bin:\$PATH"' \>\> \~/.zshrc
source \~/.zshrc
npm i \-g @docusign/cli
ds

If the installation succeeds, the CLI help output lists the available commands.

Package is deprecated error

Description
When attempting to run the ds auth login command to authenticate, you repeatedly receive this message:

DEPRECATED \- This package (@docusign/agreement-cli) is deprecated and no longer receiving updates. Please use @docusign.cli instead: https\://www\.npmjs.com/package/@docusign/cli

Cause
The CLI package version that you have installed is no longer supported.

Recommendation
Run these commands:

npm uninstall \-g @docusign/agreement-cli  
npm i \-g @docusign/cli

Then retry the authentication command.

Uninstalling and reinstalling will not affect any existing catalogs, manifests, training and testing documents in your local workspace.

Repeated session expired messages

Description
When running any command, you repeatedly receive this message, and running the ds auth login command to authenticate does not resolve the issue:

Auth Token: Your session has expired Please run: Docusign auth login

Cause
The Docusign CLI config file contains invalid cached values.

Recommendation
Run this command:

rm \~/.docusign/config.json

Then run this command to authenticate against the environment that you’re working with:

ds auth login

HTTP Error 403: Forbidden message when trying to upload

Description
When attempting to upload a package, you receive this error:

HTTP Error 403: Forbidden Access forbidden. Your token may not have the required permissions.

Cause
The Docusign account that you’ve authenticated with does not have permissions for one or more features associated with the Docusign CLI.

Recommendation
Contact Docusign Support for assistance with adding the required permissions to your account.

Manifest validation errors

Before uploading your package to Agreement Manager, the CLI validates your manifest. If the manifest is misconfigured, the upload is blocked and an error message is returned. The following table lists common validation errors, their causes, and how to resolve them.

Error message	Cause	Resolution
Schema validation errors (for example, missing required fields, invalid types, invalid name identifiers)	The manifest JSON does not conform to the expected schema. Required properties may be missing, data types may be incorrect, or name fields may not be valid identifiers.	Verify that your manifest includes all required properties with the correct data types. Ensure all `key` values for custom fields and custom agreement types start with the `C_` prefix (uppercase C), followed by a letter, underscore, or dollar sign, then letters, digits, underscores, or dollar signs.
Duplicate custom field displayNames found: “label”	Two or more custom fields in the manifest share the same `displayName`.	Remove the duplicate custom field label so that each custom field has a unique display name.
Duplicate custom agreement type displayNames found: “label”	Two or more custom agreement types in the manifest share the same `displayName`.	Remove the duplicate agreement type label so that each custom agreement type has a unique display name.
Duplicate custom field keys found: “name”	Two or more custom fields in the manifest share the same `key`.	Remove the duplicate custom field key so that each custom field has a unique identifier.
Duplicate custom agreement type keys found: “name”	Two or more custom agreement types in the manifest share the same `key`.	Remove the duplicate agreement type key so that each custom agreement type has a unique identifier.
Custom field displayNames must not match standard field displayNames	One or more custom field `displayName` values match a standard field label in the catalog.	Update the custom field’s `displayName` so it does not duplicate a standard field label, or remove the field if it duplicates an existing standard field.
Custom agreement type displayNames must not match standard agreement type displayNames	One or more custom agreement type `displayName` values match a standard agreement type label in the catalog.	Update the custom agreement type’s `displayName` so it does not duplicate a standard agreement type label, or remove the agreement type if it duplicates an existing standard type.
Exceeded maximum number of allowed custom fields (300)	The manifest defines more than 300 custom fields.	Reduce the number of custom fields in the manifest to 300 or fewer.
Exceeded maximum number of allowed custom agreement types (200)	The manifest defines more than 200 custom agreement types.	Reduce the number of custom agreement types in the manifest to 200 or fewer.
Exceeded maximum number of allowed custom fields with AI extractions enabled (50)	More than 50 custom fields and custom agreement types combined have `customExtractionEnabled` set to `true`.	Reduce the number of custom fields with `customExtractionEnabled` set to `true` so the total combined count of AI-enabled custom fields and custom agreement types does not exceed 50.
Exceeded maximum number of allowed custom agreement types with AI extractions enabled (15)	More than 15 custom agreement types have `customExtractionEnabled` set to `true`. Even if the combined total of AI-enabled custom fields and custom agreement types is under 50, no more than 15 custom agreement types can have AI extraction enabled.	Reduce the number of custom agreement types with `customExtractionEnabled` set to `true` to 15 or fewer.
Agreement type “type name” has AI extractions enabled but does not reference any training files in the “docs” property	A custom agreement type has `customExtractionEnabled` set to `true` but the `docs` array is empty or missing.	Add at least one training file to `{workspaceName}/{projectName}/agreement-manager/files/train/` and reference the filename in the `docs` property of the agreement type. Alternatively, set `customExtractionEnabled` to `false` if AI extraction is not needed for this type.
Training file “filename” referenced in agreement type “type name” does not exist in /files/train	A filename listed in the `docs` property of a custom agreement type does not exist in the `{workspaceName}/{projectName}/agreement-manager/files/train/` directory.	Add the missing file to the `agreement-manager/files/train/` directory, or update the `docs` property in the manifest to reference a file that exists in that directory.
The following custom fields are defined but not referenced by any agreement type: “field label”	A custom field is defined in the manifest’s `fields` array but is not referenced in the `fields.customFields` array of any agreement type (standard or custom) in the manifest. This validation applies only to fields newly created in the manifest, not to fields already in the custom catalog.	Add the custom field’s `displayName` to the `fields.customFields` array of at least one agreement type in the manifest, or remove the field definition if it is not needed.
Agreement type “type label” references undefined field label “field label”	An agreement type references a field label in `additionalStandardFields` or `customFields` that does not exist in either the standard catalog or the manifest’s custom field definitions.	Verify that the field label matches exactly (case-sensitive) with either a standard field label from the catalog or a custom field label defined in the manifest’s `fields` array.

Reprocessing errors

These errors may be displayed if a reprocess command cannot be executed successfully:

Error message	Cause	Resolution
—agreement-types and —fields are mutually exclusive. Provide one or the other.	Both `--agreement-types` and `--fields` flags are provided in the same command.	Remove one of the flags from the `reprocess` command and re-enter it.
Agreement type(s) are not present in your account: <types>	One or more agreement type display names provided with the `--agreement-types` option do not match any agreement type defined in the catalog.	Check the `displayName` values using the get catalog command, and re-enter the `reprocess` command with the correct names.
The following custom field(s) are not AI enabled in your account: <fields>	One or more custom fields provided with the `--fields` option have `customExtractionEnabled` set to `false`.	You can do either of the following for the fields listed in the error message: Remove them from the `reprocess` command and re-enter it. Update the manifest file to set their `customExtractionEnabled` property to `true`, and upload the package.
The following field(s) are not mapped to any agreement type in your account: <fields>	One or more field names provided with the `--fields` option are not associated with any agreement type in the catalog.	You can do either of the following for the fields listed in the error message: Remove them from the `reprocess` command and re-enter it. Update the manifest file to include them in at least one agreement type, and upload the package.

Frequently asked questions

What should I do if I get an “EPERM: operation not permitted” error when running the scaffold command?

Change to a directory that the CLI has permission to write to and rerun the command, or specify a valid directory path using the \-w option (for example, ds scaffold \-w ..\\..\\workspaces\\my\_new\_workspace \-p my\_new\_project). See Set up your workspace for more information about the scaffold command.

What is the solution if I keep seeing messages stating that @docusign/agreement-cli is deprecated?

Uninstall the deprecated package using npm uninstall \-g @docusign/agreement-cli and install the updated package with npm i \-g @docusign/cli. See Update to a new version for more information.

How do I resolve a repeated “session expired” message that isn’t fixed by logging in?

Remove the local configuration file by running rm \~/.docusign/config.json, then run ds auth login to re-authenticate against your environment. See Authenticate for more information about the auth login command.

What are the limits for custom fields and custom agreement types in a manifest?

A manifest allows up to 300 custom fields and up to 200 custom agreement types. Additionally, no more than 50 total custom fields and custom agreement types combined (and no more than 15 custom agreement types) can have AI extractions enabled. See Manifest reference for more information about limits.

Next steps

Explore the AI tools available to help you build and manage your Agreement Manager configuration more efficiently.
Get an overview of common Docusign CLI implementation scenarios.