> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Troubleshooting 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](/docusign-cli/get-started/#set-up-your-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](https://support.docusign.com/s/contactSupport) 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: \ | 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](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs/#retrieve-current-configuration) command, and re-enter the `reprocess` command with the correct names. | | The following custom field(s) are not AI enabled in your account: \ | 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](/docusign-cli/configure-agreement-types-and-fields/manifest-reference/) to set their `customExtractionEnabled` property to `true`, and [upload the package](/docusign-cli/configure-agreement-types-and-fields/upload-package/). | | The following field(s) are not mapped to any agreement type in your account: \ | 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](/docusign-cli/configure-agreement-types-and-fields/manifest-reference/) to include them in at least one agreement type, and [upload the package](/docusign-cli/configure-agreement-types-and-fields/upload-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](/docusign-cli/get-started/#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](/docusign-cli/get-started/#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](/docusign-cli/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](/docusign-cli/configure-agreement-types-and-fields/manifest-reference/) for more information about limits. ## Next steps * Explore the [AI tools](/docusign-cli/ai-tools/) available to help you build and manage your Agreement Manager configuration more efficiently. * Get an overview of common Docusign CLI [implementation scenarios](/docusign-cli/use-cases/).