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

> Master error staging and debugging in auth0-deploy-cli. Learn to diagnose deployment issues with enriched error objects and activate debug mode for full stack traces and retry logs.

- Repository: [Auth0/auth0-deploy-cli](https://github.com/auth0/auth0-deploy-cli)
- Tags: deep-dive
- Published: 2026-02-25

---

**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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/index.ts) enriches the error object with two critical properties:

```typescript
// 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`:

```bash

# Run deployment with maximum verbosity

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

```

According to [`src/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/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:

```bash
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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/index.ts) (lines 74-76) outputs the complete error stack trace in addition to the staged error message:

```typescript
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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/index.ts) (lines 296-301), this callback outputs messages indicating the resource type, attempt number, and delay duration:

```text
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:

```typescript
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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/logger.ts) and [`src/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/index.ts).
- **Rate limit resilience**: The `retryWithExponentialBackoff` helper in [`src/tools/auth0/handlers/default.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/logger.ts) for log level determination and [`src/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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.