Error Handling

Putnami's CLI is designed to provide clear, actionable feedback when things go wrong, and robust recovery options for complex automation pipelines.

Understanding Errors

When a command fails, Putnami provides structured output to help you diagnose the issue.

Anatomy of an Error

In the default text mode, an error looks like this:

  Error: Unknown command 'deploy'

  → Did you mean 'deploy-app'?
  → Run '--help' for usage information.

If you are running in CI or automation context with --output json, the error is machine-readable:

{
  "error": "Unknown command 'deploy'",
  "code": "COMMAND_NOT_FOUND",
  "exitCode": 1,
  "suggestions": [
    "Did you mean 'deploy-app'?",
    "Run '--help' for usage information."
  ],
  "command": "putnami deploy"
}

Common Error Types

• Validation Error: Determining that flags or arguments are incorrect.
• Configuration Error: Issues with your workspace configuration or project settings.
• Execution Error: Failures during the actual running of a job (e.g., a build script failed).
• Command Not Found: Typo or missing alias.

Reliability Flags

For long-running jobs or unstable environments (like network-heavy tasks), Putnami provides flags to increase reliability.

Automatic Retries

Use --retry <N> to automatically retry failed jobs. This is useful for transient failures like network timeouts.

# Retry up to 3 times if the build fails
putnami run build --retry 3

Putnami uses smart detection to only retry errors that look transient (e.g., network socket errors, 503s). Configuration errors are never retried.

Continue on Error

By default, Putnami stops the entire execution queue if a single job fails (Fail Fast). Use --continue-on-error to proceed with independent jobs even if one fails.

# Run tests for all projects, even if some fail
putnami run test --continue-on-error

Note: Dependent jobs will still be skipped. If pkg-b depends on pkg-a, and pkg-a fails, pkg-b will be skipped even with this flag.

Diagnostics

Verbose Mode

To get full stack traces and debug logs, use the --verbose flag (or -v).

putnami run build -v

Exit Codes

Putnami uses semantic exit codes to help you decide how to handle failures in scripts:

• 0: Success.
• 1: Generic Run Error (Execution failed).
• 9: Invalid Usage (Bad flags/arguments).
• 10: Configuration Error (Invalid config file).

See Exit Codes for the full list.