***

title: Troubleshoot SDK errors in Postman
updated: 2026-02-04T00:00:00.000Z
max-toc-depth: 2
----------------

The [SDK commands](/docs/sdk-generator/sdk-cli/) in the Postman CLI can emit errors and warnings based on their current implementations under `lib/commands/sdk/*` and related services.

The following sections are organized by command and cross-functional concerns:

* `postman sdk generate`
* `postman sdk list`
* `postman sdk get`,`postman sdk fetch`, and `postman sdk download`
* `postman sdk connect`
* Shared build, artifact, filesystem, configuration, language, and HTTP-status handling.

<Note>
  All SDK subcommands share the same authentication mechanism. When no API key or access token is available, they surface a common *no authorization data* error.
</Note>

## Common authentication and authorization errors

These apply to all SDK subcommands that wrap `postmanUtil.addApiKeyToOptions` or `withAuthentication` and to some helper flows (`identifyIdType`, `validateCollection`, workspace lookups, and the SDK generator API).

### Missing CLI authentication

The source of this message is:

* `ERROR_MESSAGES.NO_AUTHORIZATION_DATA_WITH_REFERENCE` (used in `sdk/generate.ts`, `sdk/list.ts`, `sdk/get.ts`, `sdk/authenticated-action.ts`)
* Ad-hoc message in `sdk/connect.ts` workspace lookup and specification/collection helpers.

If the error message is:

```bash
Error: No authorization data found. Please use the `postman login` command.
```

or (when surfaced through the shared error message constant):

```bash
Error: No authorization data found. Please use the `postman login` command.

  Refer: https://learning.postman.com/docs/postman-cli/postman-cli-options/#postman-login
```

It occurs in the following cases:

* When running any of the following without a valid Postman API key or access token:
  * `postman sdk generate <id>`
  * `postman sdk list <collectionId>`
  * `postman sdk get|fetch|download <buildId>`
  * `postman sdk connect github <id>` (initial auth check)
* When calling helpers that require auth:

  * `identifyIdType` / `validateCollection`
  * Workspace discovery in `sdk/connect.ts`
  * `createSDKGeneratorService` when both `accessToken` and `postmanApiKey` are missing:

  ```bash
  Error: Authentication required. Please provide accessToken or postmanApiKey.
  ```

The expected response is:

* The command exits with status code `1` after logging the error to `stderr`.

To resolve this error, do the following:

* Run `postman login` to create or refresh the local access token.
* Or provide `POSTMAN_API_KEY` / `--api-key` as documented in the CLI auth docs.
* Ensure the same account has access to the collections/specifications you are working with.

## Generate command errors and warnings

### Collection validation errors

If the error message is:

```bash
Error: Collection validation failed: Collection "12345-abcde-67890" not found. Please verify the collection ID and your access permissions.
```

It occurs in the following cases:

* When the collection doesn't exist.
* When the user doesn't have access to the collection.

To resolve this error, do the following:

* Verify the collection ID is correct.
* Check that you have access to the collection.
* Ensure you're authenticated with the correct account.

If the error message is:

```bash
Error: Collection validation failed. Please check the collection ID and your access permissions.
```

It occurs in the following cases:

* When collection validation fails for any reason.

To resolve this error, do the following:

* Verify the collection ID.
* Check your access permissions.
* Ensure you're authenticated.

### Collection identifier errors

If the error message is:

```bash
Error: Invalid ID provided. Expected a Postman Collection ID or Specification ID.
```

It occurs in the following cases:

* When the ID is null, undefined, or not a string.

If the error message is:

```bash
Error: URLs are not currently supported. Please provide a Postman Collection ID or Specification ID (UUID).
```

It occurs in the following cases:

* When the ID is a URL (starts with `http://` or `https://`).

If the error message is:

```bash
Error: File paths are not currently supported. Please provide a Postman Collection ID or Specification ID (UUID).
```

It occurs in the following cases:

* When the ID looks like a file path (for example ends with `.json`, `.yaml`, `.yml`, or contains `/` or `\`).

If the error message is:

```bash
Error: Invalid ID: "invalid-id". Expected a Postman Collection ID or Specification ID (UUID format).
```

It occurs in the following cases:

* When the ID format is invalid.
* When it doesn't match a supported UUID format.

To resolve this error, do the following:

* Use a valid Postman Collection ID or specification ID in UUID format. Supported formats include:
  * Standard UUID (8-4-4-4-12), typically used for specifications.
  * Prefixed UUID (8-8-4-4-4-12), typically used for collections.

### Language selection errors

If the error message is:

```bash
Error: Cannot use both --all and --language flags. Please use either --all to generate all languages or --language to specify specific languages.
```

It occurs in the following cases:

* When both `--all` and `--language` flags are used together.

To resolve this error, do the following:

* Use either `--all` to generate all languages, or `--language` to specify specific languages.

If the error message is:

```bash
Error: No languages selected. SDK generation cancelled.
```

It occurs in the following cases:

* When the user cancels the language selection prompt.
* When no languages are selected from the interactive prompt.

To resolve this error, do the following:

* Re-run the command and select at least one language.
* Or use `--language` flag to specify languages directly.

If the error message is:

```bash
Error: Unsupported language(s): ruby, javascript. Supported languages: typescript, python, java
```

It occurs in the following cases:

* When an unsupported language is specified.

To resolve this error, do the following:

* Use one of the supported languages: `typescript`, `python`, `java`

If the error message is:

```bash
Error: At least one language must be specified.
```

It occurs in the following cases:

* When no valid languages are provided after filtering.

### Configuration file errors

If the error message is:

```bash
Error: Failed to load config file: Config file not found: /path/to/config.json
```

It occurs in the following cases:

* When the specified config file doesn't exist.

If the error message is:

```bash
Error: Failed to load config file: Failed to fetch config from URL: <error details>
```

It occurs in the following cases:

* When fetching a config file from a URL fails.

If the error message is:

```bash
Error: Failed to load config file: Failed to read config file: <error details>
```

It occurs in the following cases:

* When reading a local config file fails.

If the error message is:

```bash
Error: Failed to load config file: Failed to parse config file: <error details>
```

It occurs in the following cases:

* When the config file contains invalid JSON.

If the error message is:

```bash
Error: Failed to load config file: Config file validation failed:
<validation errors>
```

It occurs in the following cases:

* When the config file doesn't match the expected schema.

To resolve this error, do the following:

* Check the config file format against the schema.
* Ensure all required fields are present.
* Validate JSON syntax.

### SDK generation API errors

If the error message is:

```bash
Error: SDK generation failed: <API error message>
Rate limit exceeded. Please try again later.
Rate limit resets at: 3:45:30 PM
```

It occurs in the following cases:

* When the API rate limit is exceeded (HTTP 429).

To resolve this error, do the following:

* Wait until the rate limit resets.
* Reduce the frequency of requests.

If the error message is:

```bash
Error: SDK generation failed: <API error message>
You do not have permission to generate SDKs. Please check your account permissions.
```

It occurs in the following cases:

* When the user doesn't have permission to generate SDKs (HTTP 403).

To resolve this error, do the following:

* Check your account permissions.
* Contact your administrator if needed.

If the error message is:

```bash
Error: Build polling failed: <error message>
```

It occurs in the following cases:

* When polling for build status fails.
* When build polling times out.

To resolve this error, do the following:

* Check your network connection.
* Try again later.
* Check build status manually.

If the error message is:

```bash
Error: Failed to initialize SDK service: <error message>
```

It occurs in the following cases:

* When the SDK generator service fails to initialize.

To resolve this error, do the following:

* Check your authentication.
* Verify network connectivity.
* Try again.

### PR creation errors

If the error message (specification ID with `--pr`) is:

```bash
Error: PR creation is not supported for specifications. The integrations API does not currently support specifications. Please use a collection ID instead, or omit the --pr flag. Support for specifications is being worked on and may be available in a future release.
```

It occurs in the following cases:

* When `postman sdk generate <specificationId> --pr` is used (PRs are only supported for collection IDs, not specification IDs).

This warning message (generic PR failure) appears:

```bash
⚠ PR creation failed: <error message>
```

It occurs in the following cases:

* When PR creation fails (non-fatal, doesn't stop SDK generation).

<Note>
  This is a warning, not an error. SDK generation continues even if PR creation fails.
</Note>

## List command errors

### Status validation errors

If the error message is:

```bash
Error: Invalid status: "invalid-status". Must be one of: IN_PROGRESS, SUCCESS, FAILURE (case-insensitive)
```

It occurs in the following cases:

* When an invalid status filter is provided.

To resolve this error, do the following:

* Use one of: `in-progress`, `success`, `failure` (case-insensitive)

### API errors

If the error message is:

```bash
Error: Failed to list builds: Rate limit exceeded. Please try again later.
```

It occurs in the following cases:

* When rate limit is exceeded (HTTP 429).

If the error message is:

```bash
Error: No builds found for this collection.
```

It occurs in the following cases:

* When no builds exist for the collection (HTTP 404).

To resolve this error, do the following:

* Generate a build first using `postman sdk generate`.

If the error message is:

```bash
Error: Server error while fetching builds. Please try again later.
```

It occurs in the following cases:

* When a server error occurs (HTTP 500+).

If the error message is:

```bash
Error: Failed to list builds: <error message>
HTTP Status: <status code>
```

It occurs in the following cases:

* When verbose mode is enabled and an error occurs.
* Shows the HTTP status code for debugging.

### Download errors

If the error message is:

```bash
Error: Error fetching build details: <error message>
```

It occurs in the following cases:

* When fetching full build details fails during download.

If the error message is:

```bash
Error: Error downloading SDKs: <error message>
```

It occurs in the following cases:

* When downloading SDKs from a build fails.

## Get/Fetch command errors

### Build ID validation errors

If the error message is:

```bash
Error: Invalid build ID provided. Build ID must be a positive number.
```

It occurs in the following cases:

* When the build ID isn't a valid positive number.

To resolve this error, do the following:

* Provide a valid numeric build ID.

### Build not found errors

If the error message is:

```bash
Error: Build not found: 12345
Please verify the build ID is correct.
```

It occurs in the following cases:

* When the build ID doesn't exist (HTTP 404).

To resolve this error, do the following:

* Verify the build ID is correct.
* List builds first to see available build IDs.

If the error message is:

```bash
Error: No SDKs found in build
```

It occurs in the following cases:

* When the build has no successful SDK artifacts.

To resolve this error, do the following:

* Check if the build completed successfully.
* Try a different build ID.

If the error message is:

```bash
Error: No SDK found for language: TYPESCRIPT
Available: PYTHON, JAVA
```

It occurs in the following cases:

* When requesting a specific language that doesn't exist in the build.

To resolve this error, do the following:

* Use one of the available languages.
* Or omit the `--language` flag to download all available SDKs.

If the error message is:

```bash
Error: No SDK artifacts found in build
```

It occurs in the following cases:

* When no SDK artifacts are found in the build.

### Download errors

If the error message is:

```bash
  ✗ Failed: No artifact URL found and collection ID is missing
```

It occurs in the following cases:

* When an artifact has no URL and the collection ID is missing.

If the error message is:

```bash
  ✗ Failed: <error message>
```

It occurs in the following cases:

* When downloading a specific SDK language fails.

If the error message is:

```bash
Error: Build fetch failed: <error message>
Rate limit exceeded. Please try again later.
Rate limit resets at: 3:45:30 PM
```

It occurs in the following cases:

* When rate limit is exceeded (HTTP 429).

If the error message is:

```bash
Error: Failed to initialize SDK service: <error message>
```

It occurs in the following cases:

* When SDK service initialization fails.

## Connect command errors

### Provider validation errors

If the error message is:

```bash
Error: Unsupported provider "gitlab". Currently only "github" is supported.
```

It occurs in the following cases:

* When an unsupported provider is specified.

To resolve this error, do the following:

* Use `github` as the provider.

### Language validation errors

If the error message is:

```bash
Error: Language is required. Use --language or -l flag.
Supported languages: typescript, python, java
```

It occurs in the following cases:

* When language isn't provided.

To resolve this error, do the following:

* Use `--language` or `-l` flag to specify a language.

If the error message is:

```bash
Error: Invalid language: "ruby". Must be one of: typescript, python, java
```

It occurs in the following cases:

* When an unsupported language is specified.

To resolve this error, do the following:

* Use one of the supported languages.

### Workspace errors

If the error message is:

```bash
Error: No workspaces found for this user.
```

It occurs in the following cases:

* When the user has no accessible workspaces.

If the error message is:

```bash
Error: Collection 12345-abcde-67890 not found in any of your workspaces. Please provide the workspace ID manually using the --workspace option.
```

It occurs in the following cases:

* When the collection can't be found in any workspace.

To resolve this error, do the following:

* Provide the workspace ID manually using `--workspace` option.

### OAuth authentication errors

If the error message is:

```bash
Error: Authentication timeout. Please try again.
```

It occurs in the following cases:

* When OAuth authentication takes too long (5 minutes timeout).

To resolve this error, do the following:

* Try the authentication process again.
* Complete the browser authentication promptly.

If the error message is:

```bash
Error: OAuth token not available. Please try again.
```

It occurs in the following cases:

* When OAuth token is missing after authentication.

To resolve this error, do the following:

* Re-run the connect command.
* Complete the OAuth flow again.

### Repository errors

If the error message is:

```bash
Error: No repositories found for <owner>
```

It occurs in the following cases:

* When the selected owner/organization has no repositories.

To resolve this error, do the following:

* Select a different owner/organization.
* Ensure the owner has accessible repositories.

If the error message is:

```bash
Error: No branches found for <owner>/<repository>
```

It occurs in the following cases:

* When the repository has no branches.

To resolve this error, do the following:

* Ensure the repository has at least one branch.
* Check repository access permissions.

### Integration errors

If the error message is:

```bash
Error: Integration <id> is missing required configuration (owner, repo, or access token)
```

It occurs in the following cases:

* When an integration is missing required configuration.

This warning message appears:

```bash
Warning: Could not fetch GitHub user info: <error message>
```

It occurs in the following cases:

* When GitHub user info can't be fetched (non-fatal).

This warning message appears:

```bash
Warning: Failed to delete integration <id>: <error message>
```

It occurs in the following cases:

* When deleting an existing integration fails (non-fatal).

If the error message is:

```bash
Error: No files were copied to the repository
```

It occurs in the following cases:

* When no SDK files are found to copy to the repository.

To resolve this error, do the following:

* Ensure SDKs were generated successfully.
* Check the output directory contains SDK files.

If the error message is:

```bash
✗ Failed to create PR for integration <id> (<language>): <error message>
```

It occurs in the following cases:

* When creating a PR for a specific integration fails.

If the error message is:

```bash
✗ Failed to create <count> pull request(s)
```

It occurs in the following cases:

* When one or more PRs fail to be created.

## Build completion errors

### Build status errors

If the error message is:

```bash
✗ Build failed

Failed artifacts:
  ✗ typescript
    <error details>
  ✗ python
    <error details>

Warnings:
  ⚠ <warning message>
```

It occurs in the following cases:

* When a build fails completely.
* Shows failed artifacts and their errors.

This warning message appears:

```bash
⚠ Build completed with partial success

Duration: 45s

Failed to generate some SDKs:
  ✗ typescript
    <error details>

Warnings:
  ⚠ <warning message>

✓ Successfully generated 2 SDK(s), 1 failed
```

It occurs in the following cases:

* When a build completes with some successful and some failed artifacts.

If the error message is:

```bash
Error: SDK generation failed. Check the error details above for more information.
```

It occurs in the following cases:

* When build completion handling fails.

### Download errors

If the error message is:

```bash
Error: SDK generation cancelled. Existing directories were not overwritten.
```

It occurs in the following cases:

* When user declines to overwrite existing SDK directories.

To resolve this error, do the following:

* Use `--yes` flag to automatically overwrite.
* Or manually remove existing directories.

If the error message is:

```bash
✗ <language>: <error message>
```

It occurs in the following cases:

* When downloading a specific language SDK fails.

## Resource validation errors

### Collection validation errors

If the error message is:

```bash
Error: Collection ID is required for validation.
```

It occurs in the following cases:

* When collection ID is missing.

If the error message is:

```bash
Error: Collection "12345-abcde-67890" not found. Please verify the collection ID and your access permissions.
```

It occurs in the following cases:

* When collection doesn't exist or user lacks access.

## Configuration errors

### Config file errors

If the error message is:

```bash
Error: Config file not found: /path/to/config.json
```

It occurs in the following cases:

* When the specified config file doesn't exist.

If the error message is:

```bash
Error: Failed to fetch config from URL: <error message>
```

It occurs in the following cases:

* When fetching config from URL fails.

If the error message is:

```bash
Error: Failed to read config file: <error message>
```

It occurs in the following cases:

* When reading a local config file fails.

If the error message is:

```bash
Error: Failed to parse config file: <error message>
```

It occurs in the following cases:

* When config file contains invalid JSON.

If the error message is:

```bash
Error: Config file validation failed:
<validation error details>
```

It occurs in the following cases:

* When config file doesn't match the expected schema.

## Language validation errors

### Language format errors

If the error message is:

```bash
Error: Unsupported language(s): ruby, javascript. Supported languages: typescript, python, java
```

It occurs in the following cases:

* When unsupported languages are specified.

To resolve this error, do the following:

* Use supported languages: `typescript`, `python`, `java`

If the error message is:

```bash
Error: At least one language must be specified.
```

It occurs in the following cases:

* When no valid languages are provided.

If the error message is:

```bash
Error: Could not extract language from bucket key: <bucket key>
```

It occurs in the following cases:

* When language can't be extracted from artifact bucket key.

## File system errors

### Download errors

If the error message is:

```bash
Error: Download failed: <error message>
```

It occurs in the following cases:

* When downloading an artifact fails.

If the error message is:

```bash
Error: HTTP <status code>: Failed to download artifact
```

It occurs in the following cases:

* When artifact download returns an error status code.

If the error message is:

```bash
Error: Failed to write file: <error message>
```

It occurs in the following cases:

* When writing downloaded file to disk fails.

To resolve this error, do the following:

* Check disk space.
* Verify write permissions.
* Check file path validity.

### Artifact errors

If the error message is:

```bash
Error: Artifact does not contain SDK metadata or bucket key
```

It occurs in the following cases:

* When artifact is missing required metadata.

If the error message is:

```bash
Error: SDK Generator Service and collectionId are required to fetch download URL
```

It occurs in the following cases:

* When required parameters are missing to fetch download URL.

If the error message is:

```bash
Error: Artifact URL is missing
```

It occurs in the following cases:

* When artifact has no download URL.

## HTTP status code errors

### Rate limit (429)

If the error message is:

```bash
Error: <operation> failed: <error message>
Rate limit exceeded. Please try again later.
Rate limit resets at: <time>
```

It occurs in the following cases:

* When API rate limit is exceeded.

To resolve this error, do the following:

* Wait until the rate limit resets.
* Reduce request frequency.

### Forbidden (403)

If the error message is:

```bash
Error: SDK generation failed: <error message>
You do not have permission to generate SDKs. Please check your account permissions.
```

It occurs in the following cases:

* When user lacks permission for the operation.

To resolve this error, do the following:

* Check account permissions.
* Contact administrator.

### Not found (404)

If the error message is:

```bash
Error: Build not found: <buildId>
Please verify the build ID is correct.
```

It occurs in the following cases:

* When resource doesn't exist.

To resolve this error, do the following:

* Verify the ID is correct.
* Check if resource was deleted.

### Server error (500+)

If the error message is:

```bash
Error: Server error while fetching builds. Please try again later.
```

It occurs in the following cases:

* When server encounters an error.

To resolve this error, do the following:

* Retry the operation.
* Check Postman status page.
* Contact support if issue persists.

## General error format

Most errors follow this format:

```bash
Error: <error message>
```

Some errors include additional context:

```bash
Error: <operation> failed: <detailed error>
<additional context>
<resolution steps>
```

Warnings (non-fatal) use this format:

```bash
⚠ <warning message>
```

## Notes for technical writers

### Actual messages vs. published text

The messages above are exactly what the CLI prints today (or their dynamic templates). Public docs can:

* Keep these verbatim in “CLI output” code blocks.
* Use friendlier, more concise explanations in prose around them.

### Linking

For each category, consider cross-linking to:

* Authentication docs (`postman login`, API key configuration).
* SDK generator conceptual overview (what “builds”, “artifacts”, and “integrations” are).
* GitHub integration docs for `postman sdk connect` and `--pr` flows.

### Keep this file current

When SDK command code changes:

* Search `lib/commands/sdk` and `lib/api/sdk-generator-service.ts` for:
  * `new Error(`,
  * `colors.red(` / `colors.yellow(` / `print.lf(` with hard-coded strings,
  * `ERROR_MESSAGES` usages,
  * `throw new Error(...)` in helpers.
* Update this document to include any new or changed messages and conditions.
* Ensure newly added languages, providers, or integration types are reflected in the supported values and error descriptions above.