Error Staging and Debugging in auth0-deploy-cli: A Complete Guide to Deployment Diagnostics

The auth0-deploy-cli implements a three-stage error staging system (load, validate, processChanges) that enriches error objects with resource type and stage metadata, while providing debug mode activation via the --debug flag or AUTH0_DEBUG environment variable to expose full stack traces and retry logging.

The auth0-deploy-cli repository provides sophisticated mechanisms for error staging and debugging that help developers diagnose deployment failures across Auth0 tenant configurations. Understanding these diagnostic capabilities is essential for troubleshooting complex infrastructure-as-code workflows and ensuring reliable CI/CD pipelines.

The Three-Stage Error Staging Architecture

The auth0-deploy-cli separates deployment workflows into three distinct stages: load, validate, and processChanges. Each stage represents a specific phase of the deployment lifecycle, allowing precise error localization when failures occur.

Stage 1: Load

During the load stage, the CLI reads configuration files from the local filesystem and converts them into internal data structures. This stage handles file I/O operations, YAML/JSON parsing, and initial data normalization for all Auth0 resource types including rules, clients, and connections.

Stage 2: Validate

The validate stage performs schema validation and cross-reference checks on the loaded configuration. This is where the ValidationError class from src/tools/validationError.ts comes into play, ensuring that resource definitions meet Auth0 API requirements before any network requests are made.

Stage 3: ProcessChanges

During processChanges, the CLI calculates differences between the local state and the remote Auth0 tenant, then executes the necessary create, update, or delete operations. This stage involves the most network I/O and utilizes the retry logic defined in src/tools/auth0/handlers/default.ts.

Error Enrichment Mechanism

When a handler throws an exception during any stage, the runStage() method in src/tools/auth0/index.ts enriches the error object with two critical properties:

// src/tools/auth0/index.ts lines 90-91
err.type = handler.type;    // e.g., 'rules', 'clients', 'connections'
err.stage = stage;          // 'load', 'validate', or 'processChanges'

This enrichment allows the top-level error handler to produce diagnostic messages that specify exactly which resource type failed and during which stage, significantly reducing debugging time for complex multi-resource deployments.

Activating Debug Mode in auth0-deploy-cli

The auth0-deploy-cli provides two primary mechanisms for activating debug mode, both of which increase logging verbosity and expose internal stack traces for detailed troubleshooting.

Using the --debug CLI Flag

The --debug flag is the most direct method for enabling diagnostic output. When present, the CLI sets the internal log level to debug and forces the AUTH0_DEBUG environment variable to true:

# Run deployment with maximum verbosity

npx auth0-deploy-cli import -c config.json -i ./my-config/ --debug

According to src/index.ts (lines 52-56), this flag triggers immediate environment variable injection, ensuring that all downstream components recognize the debug state.

Environment Variable Configuration

Setting AUTH0_DEBUG=true directly in the environment provides the same diagnostic capabilities as the CLI flag without modifying command-line arguments:

export AUTH0_DEBUG=true   # enable stack traces and retry logging

auth0-deploy-cli export -c config.json -f yaml -o ./out/

The src/logger.ts file reads this environment variable to determine the appropriate Winston log level, defaulting to info when undefined.

Debug Output and Stack Traces

When debug mode is active, the top-level error handler in src/index.ts (lines 74-76) outputs the complete error stack trace in addition to the staged error message:

if (process.env.AUTH0_DEBUG === 'true' && err.stack) {
  console.error(err.stack);
}

This behavior ensures that developers receive both the high-level context (resource type and stage) and the low-level execution context (line numbers and call stack) necessary for resolving complex issues.

Retry Logic and Rate Limit Handling

Transient failures, particularly Auth0 API rate limits (HTTP 429), are handled through a sophisticated retry mechanism that prevents unnecessary deployment failures while providing visibility into retry attempts.

Exponential Backoff Implementation

The retryWithExponentialBackoff helper in src/tools/auth0/handlers/default.ts implements intelligent retry logic for all API handlers. When a request returns a 429 status code, the helper:

1. Detects the rate-limit condition via error?.statusCode === 429
2. Calculates an exponential backoff delay with jitter to prevent thundering herd problems
3. Re-issues the request up to a configurable maximum number of attempts

This mechanism ensures that temporary throttling does not surface as fatal errors unless the retry limit is exhausted.

Observing Retry Attempts in Debug Mode

When AUTH0_DEBUG is enabled, the retry helper invokes an onRetry callback that logs detailed information about each retry attempt. According to src/tools/auth0/index.ts (lines 296-301), this callback outputs messages indicating the resource type, attempt number, and delay duration:

2026-02-25T12:34:56.789Z - debug: Rate limit hit for [rules]. Retrying attempt 1/3 (2000 ms)
2026-02-25T12:34:58.791Z - debug: Rate limit hit for [rules]. Retrying attempt 2/3 (4000 ms)

These debug logs are invaluable for diagnosing performance issues and understanding the temporal behavior of large-scale deployments.

Programmatic Error Handling

For developers integrating auth0-deploy-cli into custom Node.js applications or CI/CD pipelines, the staged error objects provide structured data for programmatic decision-making.

The following example demonstrates how to catch enriched errors and implement custom logging or recovery logic:

import deployCLI from 'auth0-deploy-cli';

// Run the CLI programmatically; errors contain stage & type.
try {
  await deployCLI.import(params);
} catch (err) {
  console.error(
    `Error processing ${err.type} during ${err.stage} stage: ${err.message}`
  );
  if (process.env.AUTH0_DEBUG === 'true' && err.stack) {
    console.error(err.stack);
  }
}

This pattern allows automation systems to route specific resource failures to appropriate remediation workflows—for example, retrying only processChanges failures while alerting developers about validate stage errors.

Summary

• Three-stage architecture: The auth0-deploy-cli processes deployments through load, validate, and processChanges stages, with each stage wrapped in error handling that enriches exceptions with metadata.
• Error enrichment: Errors automatically receive type (resource type) and stage (execution phase) properties via src/tools/auth0/index.ts, enabling precise failure localization.
• Debug activation: Use the --debug CLI flag or set AUTH0_DEBUG=true to enable stack trace output and verbose logging through src/logger.ts and src/index.ts.
• Rate limit resilience: The retryWithExponentialBackoff helper in src/tools/auth0/handlers/default.ts automatically retries 429 errors with exponential backoff, logging attempts when debug mode is active.
• Programmatic access: Staged errors can be caught in Node.js applications to implement custom recovery logic based on specific resource types and failure stages.

Frequently Asked Questions

How does auth0-deploy-cli categorize errors during deployment?

The CLI categorizes errors using a two-dimensional system implemented in src/tools/auth0/index.ts. Every error receives a type property indicating the Auth0 resource being processed (such as rules, clients, or connections) and a stage property indicating the execution phase (load, validate, or processChanges). This categorization occurs at lines 90-91 where the error object is enriched before being re-thrown to the top-level handler.

What is the difference between using --debug and AUTH0_DEBUG environment variable?

Both mechanisms achieve the same diagnostic outcome but differ in activation method. The --debug CLI flag, processed in src/index.ts (lines 52-56), automatically sets the AUTH0_DEBUG environment variable to true and configures the Winston logger to debug level. Setting AUTH0_DEBUG=true directly in the environment bypasses the CLI argument parsing but is checked in the same locations—src/logger.ts for log level determination and src/index.ts (line 74) for stack trace output—producing identical diagnostic behavior.

How can I handle auth0-deploy-cli errors programmatically in my Node.js application?

When importing the CLI as a module, errors thrown during import() or export() operations contain the enriched type and stage properties. Wrap the CLI call in a try/catch block and inspect these properties to determine which resource failed and during which phase. For complete diagnostic information, check process.env.AUTH0_DEBUG and output err.stack when available. This approach allows you to implement conditional logic—such as retrying only processChanges failures or alerting on validate errors—based on the structured error metadata.

Does auth0-deploy-cli automatically retry failed API requests?

Yes, the CLI implements automatic retry logic specifically for rate-limiting scenarios. The retryWithExponentialBackoff function in src/tools/auth0/handlers/default.ts detects HTTP 429 responses and retries requests using exponential backoff with jitter. This mechanism includes an onRetry callback that logs retry attempts when debug mode is active, as implemented in src/tools/auth0/index.ts (lines 296-301). The retry logic applies to transient throttling errors but does not retry other HTTP error codes, ensuring that configuration errors fail fast while temporary rate limits resolve automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}