Troubleshoot SDK errors in Postman

The SDK commands 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.

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:

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

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

$
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:

  $
  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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
Error: Unsupported language(s): swift. Supported languages: typescript, python, java, kotlin, csharp, go, php, ruby, rust

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, kotlin, csharp, go, php, ruby, rust.

If the error message is:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
⚠ PR creation failed: <error message>

It occurs in the following cases:

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

List command errors

Status validation errors

If the error message is:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
  ✗ 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:

$
  ✗ Failed: <error message>

It occurs in the following cases:

• When downloading a specific SDK language fails.

If the error message is:

$
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:

$
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:

$
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:

$
Error: Language is required. Use --language or -l flag.
$
Supported languages: typescript, python, java, kotlin, csharp, go, php, ruby, rust

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:

$
Error: Invalid language: "swift". Must be one of: typescript, python, java, kotlin, csharp, go, php, ruby, rust

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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
✗ 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:

$
✗ 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:

$
✗ 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:

$
⚠ 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:

$
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:

$
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:

$
✗ <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:

$
Error: Collection ID is required for validation.

It occurs in the following cases:

• When collection ID is missing.

If the error message is:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
Error: Unsupported language(s): swift. Supported languages: typescript, python, java, kotlin, csharp, go, php, ruby, rust

It occurs in the following cases:

• When unsupported languages are specified.

To resolve this error, do the following:

• Use supported languages: typescript, python, java, kotlin, csharp, go, php, ruby, or rust.

If the error message is:

$
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:

$
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:

$
Error: Download failed: <error message>

It occurs in the following cases:

• When downloading an artifact fails.

If the error message is:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
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:

$
Error: <error message>

Some errors include additional context:

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

Warnings (non-fatal) use this format:

$
⚠ <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.